The App Center server-to-server API is an interface that allows a Partner to query additional information from the App Center or Semrush. It may include clearing inactive users data and disabling features working outside the iframe. The interface is helpful if the standard set of JS SDK methods isn't enough to learn more about the user and to know their current status with your app.
You make a request to the App Center with JWT generated with the secret key of the certain app. The App Center responds with the bearer token for server-to-server API access. Then, you request access to the App Center server-to-server API using the received token and get the needed information.
Depending on what information you want to get from the API, you can make the following requests:
We also provide the OpenAPI scheme as a blueprint for the API, defining endpoints, data formats, authentication methods, and more.
To start working with any of the requests to the App Center server-to-server API, contact the App Center Team to get access. Without requesting access, you can use only the viewer status.
Before you start working with the API, you must get the bearer token for requesting access.
Generate a JWT using your app ID and the secret key that you have after the registration. Use the HMAC SHA256 algorithm for signing. The JWT payload contains the token issuer ID, the information owner, and the Unix timestamp which confirms that the JWT was created less than five minutes ago:
{
"aud": "app-center",
"iss": "bf860c6b-dd98-42f2-b23d-17dcec59ca0d",
"iat": 1655705801
}"aud" - the owner of the queried information, it's always "app-center","iss" - the token issuer, which is your app ID,"iat" - the timestamp of the token creation.
Make the POST request to the token issuer, using the generated token from the previous step:
POST https://api.semrush.com/app-center-api/v2/jwt-token/
Content-Type: application/json; charset=UTF-8
{
"jwt": "eyJ0...zQ6mQ"
}The App Center backend validates your JWT and responds with the bearer token:
{
"jwt": "eyJ0eXA...Q-XQtlS8-N"
}Use that token for requesting access to the App Center server-to-server API, you need to pass it every time you make a request. Remember that the token is valid only for 5 minutes.
If the validation isn't successful, you may receive a response with an error.
Note that you don't have to get the bearer token from the App Center every time you request access to the App Center server-to-server API. You can save it for some time and then reuse it instead.
The Viewer status report is needed to get user information: you can check their app subscription,
in-app products and trial availability options.
The body of the request contains only the user_id field, which is an unsigned integer - Semrush user ID:
Make the POST request to the App Center server-to-server API,
using the bearer token you got from the issuer in the previous step.
Put it in the Authorization: Bearer <token> header:
POST https://api.semrush.com/apis/v4/app-center/v2/partner/viewer-status
Content-Type: application/json; charset=UTF-8
Authorization: Bearer eyJ0eXA...elbyg
{
"user_id": 5511383
}If the validation is successful, you receive a response:
{
"meta": {
"success": true,
"status_code": 200,
"request_id": "api-flb-9854df3ada95fe20d8511e8732fbb9eb"
},
"data": {
"is_main_product_active": true,
"is_app_taken_for_free": false,
"is_main_product_trial_available": false,
"product_trials_available": ["f406843c-6838-46de-9ecc-f17c7c0dc359"],
"active_products": [
{
"id": "4fbe56d2-148c-40c4-af83-bdcbfd60c0e3",
"value": 1
},
{
"id": "3e17cdb2-5b75-4959-bf16-97221c3bd0a8",
"value": 1
}
],
"extra_user_data": {
"is_main_product_trial_active": false,
"active_product_trials": ["e67176df-f062-4ab6-817a-e2f68878bba8"]
}
}
}data field contains all necessary bussiness information about user's subscription to the app.data field may not contain any fields inside. It means that the user doesn't have subscription to the app
regardless of what monetization option is used.data field is the same as described in JWT reference.Since you need to make at least two requests to get some information about user from the App Center server-to-server API there are two validations on requests to:
In case of error the response JSON data should always look like:
{
"message": "JWT processing error: <MESSAGE CONTENT>",
"message_code": "JWT_PROCESSING_ERROR",
"code": 400
}The message content can be different:
Invalid request body: Check the body of the request you are making, you probably missed it.No jwt data in request body: You missed the jwt field in the request payload.Incorrect JWT: The JWT content is not valid, it must contain the fields described
in the reference;Invalid app id: You missed the iss field in JWT, or it doesn't match the UUID4 format.App not found: The app ID provided in the iss field is incorrect.JWT token is expired or issued at wrong date – token is expired, you need to generate another one.If the validation isn't successful, you may receive a response with an error message:
{
"meta": {
"success": false,
"status_code": 403,
"request_id": "api-flb-a2644bf48589ebe941e9f9d1b907e95a"
},
"error": {
"code": 403,
"message": "Forbidden"
}
}An example of the response with the wrong value in the user_id field:
{
"meta": {
"success": false,
"status_code": 404,
"request_id": "api-flb-c6d20e2c94aa4df35d9c6d6bf1716cc9"
},
"error": {
"code": 404,
"message": "Not Found"
}
}