Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 6:00 PM (EST/EDT)
Monday - Friday
Need help?
Telephone
United States
United States
Canada
United Kingdom
Spain
France
Italy
Germany
Australia
+1 (800) 815 - 9959
10:00 AM - 6:00 PM (EST/EDT)
Monday - Friday
Endpoint
https://api.semrush.com/apis/v4/
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)
Name | Description |
---|---|
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.
Request example
$ open https://oauth.semrush.com/dag/auth/verify_code?code=AVZV-MSPD
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.
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.
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.
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" } ] }
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" } }