跳转至主内容

概览

AdGuard DNS 提供一个 REST API，可以使用它集成在您的应用程序中。

身份验证​

API keys​

When included in the request header, API keys can be used to authorize requests to User API.

Request example​

$ curl 'https://api.adguard-dns.io/oapi/v1/devices' -i -X GET \
    -H 'Authorization: ApiKey {api_key}'

Generating API keys​

To issue or revoke API keys, go to the corresponding subsection of User preferences.

Access tokens​

When included in the request header, access tokens can be used to authorize requests to User API.

Request example​

$ curl 'https://api.adguard-dns.io/oapi/v1/devices' -i -X GET \
    -H 'Authorization: Bearer {access_token}'

示例响应​

Make a POST request for the following URL with the given params to generate the access_token:

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

参数详细信息
username账号邮箱
password账号密码
mfa_token双重身份验证令牌（如果已在账户设置中启用）

In the response, you will get both access_token and refresh_token.

  • access_token 将在指定的几秒后过期（由响应中的 expires_in 参数决定） You can regenerate a new access_token using the refresh_token (Refer to Generating access tokens from refresh tokens).

  • refresh_token 是永久性的。 To revoke a refresh_token, refer to Revoking refresh tokens.

Request example​
$ 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'
Response example​
{
  "access_token": "jTFho_aymtN20pZR5RRSQAzd81I",
  "token_type": "bearer",
  "refresh_token": "H3SW6YFJ-tOPe0FQCM1Jd6VnMiA",
  "expires_in": 2620978
}

Generating access tokens from refresh tokens​

Access tokens have limited validity. Once it expires, your app will have to use the refresh token to request for a new access token.

Make the following POST request with the given params to get a new access token:

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

参数详细信息
refresh_token必须使用 REFRESH TOKEN 来生成新的访问令牌。
Request example​
$ 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'
Response example​
{
  "access_token": "xQnT7GYT6Ag--3oY_EcOOdXe-I0",
  "token_type": "bearer",
  "refresh_token": "H3SW6YFJ-tOPe0FQCM1Jd6VnMiA",
  "expires_in": 2627999
}

Revoking refresh tokens​

To revoke a refresh token, make the following POST request with the given params:

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

Request example​
$ curl 'https://api.adguard-dns.io/oapi/v1/revoke_token' -i -X POST \
    -d 'token=H3SW6YFJ-tOPe0FQCM1Jd6VnMiA'
参数详细信息
refresh_token等待撤销的 REFRESH TOKEN

Authorization endpoint​

danger

To access this endpoint, you need to contact us at devteam@adguard.com. Please describe the reason and use cases for this endpoint, as well as provide the redirect URI. Upon approval, you will receive a unique client identifier, which should be used for the client_id parameter.

The /oapi/v1/oauth_authorize endpoint is used to interact with the resource owner and get the authorization to access the protected resource.

The service redirects you to AdGuard to authenticate (if you are not already logged in) and then back to your application.

The request parameters of the /oapi/v1/oauth_authorize endpoint are:

参数详细信息
response_type告诉授权服务器要执行哪个授权。
client_id请求授权的 OAuth 客户端的 ID。
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

To inform the authorization server which grant type to use, the response_type request parameter is used as follows:

  • 对于隐式授权，使用 response_type=token 包含访问令牌。

A successful response is 302 Found, which triggers a redirect to redirect_uri (which is a request parameter). The response parameters are embedded in the fragment component (the part after the # symbol) of the redirect_uri in the Location header.

例如：

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

API​

参考资料​

Please see the method’s reference.

OpenAPI spec​

OpenAPI specification is available at https://api.adguard-dns.io/swagger/openapi.json.

You can use different tools to view the list of available API methods. For instance, you can open this file in https://editor.swagger.io/.

更新日志​

The complete AdGuard DNS API changelog is available on this page.

反馈​

If you would like this API to be extended with new methods, please email us to devteam@adguard.com and let us know what you would like to be added.