Merge pull request #200 from AdguardTeam/add-dns-api-version-1-8

Add DNS API version 1.8 (authorization endpoint)

docs/private-dns/api/changelog.md

@@ -12,6 +12,15 @@ toc_max_heading_level: 3
 
 This article contains the changelog for [AdGuard DNS API](private-dns/api/overview.md).
 
+## v1.8
+
+*Released on April 20, 2024*
+
+- Added support for DNS-over-HTTPS with authentication:
+    - New operation — reset DNS-over-HTTPS password for device
+    - New device setting — `detect_doh_auth_only`. Disables all DNS connection methods except DNS-over-HTTPS with authentication
+    - New field in Device DNSAddresses — `dns_over_https_with_auth_url`. Indicates the URL to use when connecting using DNS-over-HTTPS with authentication
+
 ## v1.7
 
 *Released on March 11, 2024*

docs/private-dns/api/overview.md

@@ -103,6 +103,45 @@ $ curl 'https://api.adguard-dns.com/oapi/v1/revoke_token' -i -X POST \
 |:----------------- |:-------------------------------------- |
 | **refresh_token** | `REFRESH TOKEN` which is to be revoked |
 
+### Authorization endpoint
+
+> To access this endpoint, you need to contact us at **[email protected]**.
+> 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:
+
+| Parameter         | Description             |
+|:------------------|:------------------------|
+| **response_type** | Tells the authorization server which grant to execute |
+| **client_id**     | The ID of the OAuth client that asks for authorization |
+| **redirect_uri**  | Contains a URL. A successful response from this endpoint results in a redirect to this URL |
+| **state**         | An opaque value used for security purposes. If this request parameter is set in the request, it is returned to the application as part of the **redirect_uri** |
+| **aid**           | Affiliate identifier |
+
+For example:
+
+```http request
+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:
+
+- For the Implicit grant, use **response_type=token** to include an access 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 `#`) of the **redirect_uri** parameter in the **Location** header.
+
+For example:
+
+```http request
+HTTP/1.1 302 Found
+Location: REDIRECT_URI#access_token=...&token_type=Bearer&expires_in=3600&state=1jbmuc0m9WTr1T6dOO82
+```
+
 ### Accessing API
 
 Once the access and the refresh tokens are generated, API calls can be made by passing the access token in the header.

docs/private-dns/api/reference.md

@@ -13,7 +13,7 @@ toc_max_heading_level: 4
 
 This article contains documentation for [AdGuard DNS API](private-dns/api/overview.md). For the complete AdGuard DNS API changelog, visit [this page](private-dns/api/changelog.md).
 
-## Current version: 1.7
+## Current version: 1.8
 
 ### /oapi/v1/account/limits