Обзор

AdGuard DNS предоставляет REST API, который вы можете использовать в своих приложениях.

Аутентификация

Генерация токена доступа

Сделайте POST-запрос с указанными параметрами по следующему URL, чтобы сгенерировать access_token:

https://api.adguard-dns.io/oapi/v1/oauth_token

Параметр	Описание
имя пользователя	Email
пароль	Пароль
mfa_token	Токен двухфакторной аутентификации (если включена в настройках аккаунта)

В ответ вы получите access_token и refresh_token.

• access_token истекает через несколько секунд (срок указан в параметре expires_in). Вы можете запросить новый access_token, используя refresh_token (См.: Генерация токена доступа через продлеваемый токен).

• refresh_token генерируется один раз и затем не изменяется. Чтобы отозвать refresh_token, см.: Отзыв продлеваемого токена.

Пример запроса

$ curl 'https://api.adguard-dns.io/oapi/v1/oauth_token' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'username=user%40adguard.com' \
    -d 'password=********' \
    -d 'mfa_token=727810'

Пример ответа

{
  "access_token": "jTFho_aymtN20pZR5RRSQAzd81I",
  "token_type": "bearer",
  "refresh_token": "H3SW6YFJ-tOPe0FQCM1Jd6VnMiA",
  "expires_in": 2620978
}

Генерация токена доступа через продлеваемый токен

Токены доступа имеют ограниченное время действия. После истечения этого срока ваше приложение должно использовать продлеваемый токен для генерации нового токена доступа.

Сделайте следующий POST-запрос с указанными параметрами, чтобы получить новый токен доступа:

https://api.adguard-dns.io/oapi/v1/oauth_token

Параметр	Описание
refresh_token	Продлеваемый токен, с помощью которого должен быть сгенерирован новый токен доступа.

Пример запроса

$ curl 'https://api.adguard-dns.io/oapi/v1/oauth_token' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'refresh_token=H3SW6YFJ-tOPe0FQCM1Jd6VnMiA'

Пример ответа

{
  "access_token": "xQnT7GYT6Ag--3oY_EcOOdXe-I0",
  "token_type": "bearer",
  "refresh_token": "H3SW6YFJ-tOPe0FQCM1Jd6VnMiA",
  "expires_in": 2627999
}

Отзыв продлеваемого токена

Чтобы сбросить продлеваемый токен, сделайте следующий POST-запрос с указанными параметрами:

https://api.adguard-dns.io/oapi/v1/revoke_token

Пример запроса

$ curl 'https://api.adguard-dns.io/oapi/v1/revoke_token' -i -X POST \
    -d 'token=H3SW6YFJ-tOPe0FQCM1Jd6VnMiA'

Параметр	Описание
refresh_token	Продлеваемый токен, который должен быть сброшен

Конечная точка авторизации

Чтобы получить доступ к этой конечной точке, вам необходимо связаться с нами по адресу devteam@adguard.com. Пожалуйста, опишите причину и случаи использования этой конечной точки, а также укажите URI перенаправления. После одобрения вы получите уникальный идентификатор клиента, который следует использовать для параметра client_id.

Конечная точка /oapi/v1/oauth_authorize используется для взаимодействия с владельцем ресурса и получения разрешения на доступ к защищённому ресурсу.

Сервис перенаправляет вас в AdGuard для аутентификации (если вы ещё не вошли в систему), а затем обратно в приложение.

Параметры запроса конечной точки /oapi/v1/oauth_authorize:

Параметр	Описание
response_type	Сообщает серверу авторизации, какой грант следует выполнить
client_id	Идентификатор клиента OAuth, который запрашивает авторизацию
redirect_uri	Содержит URL-адрес. Успешный ответ от этой конечной точки приводит к перенаправлению на этот URL
state	Непрозрачное значение, используемое в целях безопасности. Если этот параметр установлен в запросе, он возвращается приложению как часть redirect_uri
aid	Идентификатор партнёра

Например:

https://api.adguard-dns.io/oapi/v1/oauth_authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=1jbmuc0m9WTr1T6dOO82

Чтобы сообщить серверу авторизации, какой тип разрешения использовать, параметр запроса response_type используется следующим образом:

• Для неявного разрешения используйте response_type=token, чтобы включить токен доступа.

Успешный ответ — 302 Found, который запускает перенаправление на параметр запроса redirect_uri. Параметры ответа встраиваются в компонент фрагмента (часть после #) параметра redirect_uri в заголовке Локация.

Например:

HTTP/1.1 302 Found
Location: REDIRECT_URI#access_token=...&token_type=Bearer&expires_in=3600&state=1jbmuc0m9WTr1T6dOO82

Получение доступа к API

После того как токен доступа и продлеваемый токен сгенерированы, получить доступ к API можно, указав токен доступа в заголовке.

• Имя заголовка должно быть Authorization
• Значение заголовка должно быть Bearer {access_token}

API

Руководство по API

Перейдите по этой ссылке, чтобы ознакомиться с руководством по методам API.

Спецификация OpenAPI

Спецификация OpenAPI доступна по адресу https://api.adguard-dns.io/static/swagger/openapi.json.

Вы можете использовать другие инструменты для просмотра списка доступных методов API. Например, вы можете открыть этот файл в https://editor.swagger.io/.

История версий

Полный список изменений AdGuard DNS API можно найти на этой странице.

Обратная связь

Если вы хотите расширить этот API, напишите нам по адресу devteam@adguard.com и расскажите, что вы хотите добавить.