contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

10:00 AM - 6:00 PM (EST/EDT)

Monday - Friday

mobile-menu

Basic docs

Version 4 divider Last updated: January 15, 2022

Get started API 4

Endpoint

https://api.semrush.com/apis/v4/

Authorization

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

Authorization: Bearer ****

Authentication

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

Step1 - Device Authorization Request

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)

Request parameters
Name Description
scope requested scopes, comma-separated string
Available scopes
Name Description
siteaudit.info Get information about your "Site Audit" projects and reports.

In response, the authorization server generates a unique device verification code and an end-user code that are valid for a limited time and includes them in the HTTP response body using the application/json format.

Request example

$ curl https://oauth.semrush.com/dag/device/code -d scope=siteaudit.info

Response example

{ "device_code": "7ee7a929306d4075b9c4020e584fe4508862f26605e37c131eb6efe2f83b6dd0", "user_code": "AVZV-MSPD", "verification_uri": "https://oauth.semrush.com/dag/auth/verify_code?code=AVZV-MSPD", "expires_in": 300, "interval": 5 }

Step 2 - User Interaction

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.

Request example

$ open https://oauth.semrush.com/dag/auth/verify_code?code=AVZV-MSPD

Step 3 - Device Access Token Request

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.

Request parameters
Name Description
grant_type value MUST be set to urn:ietf:params:oauth:grant-type:device_code
device_code the device verification code, device_code from the device authorization response, defined in Section 1

Request example

$ curl https://oauth.semrush.com/dag/device/token -d device_code=7ee7a929306d4075b9c4020e584fe4508862f26605e37c131eb6efe2f83b6dd0 -d grant_type=urn:ietf:params:oauth:grant-type:device_code

Response example

{ "access_token": "e3wLk3PtqyVPHM7Ele61OhuZFWtKCFK4O1HQslzh", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "YWza6vpqkW628wtMldRsQNalEu9k33Vg75PQiXGi" }

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.

Response format of the API

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.

Object meta
Key Type Description Optional
success boolean Status of the request Mandatory
status_code int HTTP status code Mandatory
request_id string Unique ID of the request Optional

Success response example

{ "meta": { "success": true, "status_code": 200, "request_id": "IAD-as5656as776" }, "data": [ { "id": "590e", "kind": "dog", "name": "Penny" }, { "id": "a45f", "kind": "cat", "name": "Tommy" } ] }

Object error
Key Type Description Optional
code int Error code Mandatory
message string Error message Mandatory
description string Error description Optional

Failed response example

{ "meta": { "success": false, "status_code": 400, "request_id": "IAD-123ade456" }, "error": { "code": 120200, "message": "This was bad", "description": "google.me?error=120200" } }