Basic docs

Semrush API supports authorization with the Oauth2 flow. Please pass your Oauth2 authorization token in the HTTP request header.

Authorization: Bearer ****

Semrush API supports Device Authorization Grant flow (RFC-8628) to grant Oauth2 credentials. Please follow three steps to authenticate in Semrush API.

The client initiates the authorization flow by requesting a set of verification codes from the authorization server by making an HTTP POST request to the https://oauth.semrush.com/dag/device/code endpoint.
The client makes a device authorization request to the device authorization endpoint by including the following parameter scope (requested scopes, comma-separated string)

After receiving a successful authorization response, the client displays the user_code and the verification_uri to the end user and instructs them to visit the URI. The authorizing user navigates to the "verification_uri" and being redirected to the authorization server with session state code. Authorization server redirects user back to the dag-auth with authorization code granted and original state parameter. The dag-auth exchanges returned authorization code to the access token using it's client_id and secret.

During the user interaction, the device continuously polls the token endpoint https://oauth.semrush.com/dag/device/token by HTTP method POST with the device_code provided, until the user completes the interaction, the code expires, or another error occurs. The device_code is not intended for the end user directly; thus, it should not be displayed during the interaction to avoid confusing the end user.

If the user has approved the grant, the token endpoint responds with a success response defined in Section 5.1 of RFC6749; otherwise, it responds with an error, as defined in Section 5.2 of RFC6749. In addition to the error codes defined in Section 5.2 of RFC6749, the following error codes are specified for use with the device authorization grant in token endpoint responses.

The response body contains a JSON-encoded object, which has a top-level object meta, followed by either a data object or an error object, but not both. An explanation of each of these properties can be found below.