Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5: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 - 5: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 two ways to grant OAuth2 credentials:
Use one of these options to authenticate in Semrush API.
https://oauth.semrush.com/dag/device/code
endpoint.Name | Description |
---|---|
scope | Requested scopes, comma-separated string |
user_code
and verification_uri
to the end user and instructs them to visit the URI.verification_uri
and is redirected to the authorization server with the session state code.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 https://oauth.semrush.com/dag/device/token
token endpoint using the POST HTTP method with the device_code
provided, until the user completes the interaction, the code expires, or another error occurs. The device_code
value is not intended for the end user directly; thus, it shouldn't 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 | 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 RFC 6749. Otherwise, it responds with an error, as defined in Section 5.2 of RFC 6749. In addition to the error codes defined in Section 5.2 of RFC 6749, the following error codes are specified for use with the device authorization grant in token endpoint responses.
https://oauth.semrush.com/oauth2/success?code=UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk
.UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk
.If you have the SEOquake extension installed, you may not see the code parameter in the URL. In this case, disable the extension and repeat this step.
Make a POST request using the value you copied as the value of the code parameter:
Request example
curl -L 'https://oauth.semrush.com/oauth2/access_token' -d 'client_id=seoquake' -d 'client_secret=d41d8cd98f00b204e9800998ecf8427e' -d 'grant_type=authorization_code' -d 'code=zSypMRLSwnVFtp5Z2lUkU6fX3D3WjoyUesnuytPW' -d 'redirect_uri=https%3A%2F%2Foauth.semrush.com%2Foauth2%2Fsuccess'
Response example
{ "access_token": "wz1q0IpUBLLX7fqBKJI4pUoKBLZghAKp1VmBuJy5", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" }
Use the access_token
value when making requests to the API. To get a new one when it expires, use refresh_token
:
Request example
curl -X POST -d "client_id=seoquake&client_secret=d41d8cd98f00b204e9800998ecf8427e&grant_type=refresh_token&refresh_token=KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" https://oauth.semrush.com/oauth2/access_token
Response example
{ "access_token": "u8pPo6fo2NV70QCy7USWd3iT34CenBiT8RSuEEGn", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "s99qrRuqbUdFRnum3R1HC9dTEJMOMs0IU1hJSi7W" }
The response body contains a JSON-encoded object, which has a top-level object called meta, followed by either a data object or an error object, but not both.
Key | Type | Description | Required/Optional |
---|---|---|---|
success | boolean | Request status | Required |
status_code | integer | HTTP status code | Required |
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 | Required/Optional |
---|---|---|---|
code | integer | Error code | Required |
message | string | Error message | Required |
details | array | Error details | Optional |
Failed response example
{ "meta": { "success": false, "status_code": 400, "request_id": "IAD-123ade456" }, "error": { "code": 120200, "message": "This was bad", "details": [ { "message": { "field_violations": [ { "field": "user_id", "description": "user_id must be a number" } ] } } ] } }