App API – Authentication

The App API uses OAUTH 2.0 to authenticate requests.

Application User Account

The App API requires to have an Application User Account.

An application user acts as a regular user with Admin role but can be used only in the API communication. You cannot log in with an application user to the shop Administration and you cannot use regular user account with Admin role in the App API communicaton.

Those shop actions that are being logged, when they are performed via the App API are logged under the Application user. In the shop administration, in History sections, you can see if last change was done by an Application user.

Access Token

POST /api/app/oauth/access_token

Request Body Parameters:

• grant_type: string - client_credentials
• client_id: string
• client_secret: string
• scope: string - all

Beware! These parameters are inside the request body in the application/x-www-form-urlencoded format; not in JSON, not in URL query parameters.

Request

POST /api/app/oauth/access_token HTTP/1.1
Host: yourshopname.com
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip

grant_type=client_credentials
&client_id=d194b033-1975-43e5-a083-96bdbe3ea1cd
&client_secret=164381f6-dcea-46c1-bf8f-f9f22288970c
&scope=all

Success Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "_type": "AccessToken",
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIiLCJqdGkiOiIyZjMzNmQ2NjVkODFlMGMyZjE5OWY1ZmNhOGZhMTBjMDIwZjQwNWY3NTdiYjUwZDY5YWExNzNmZWZhZTRhMDUyMWIxN2Q4ODA4NTdiYThkNiIsImlhdCI6MTYxNjA2Mjc2OCwibmJmIjoxNjE2MDYyNzY4LCJleHAiOjE2MTYwNjYzNjgsInN1YiI6ImQxOTRiMDMzLTE5NzUtNDNlNS1hMDgzLTk2YmRiZTNlYTFjZCIsInNjb3BlcyI6WyJlbWFpbCJdfQ.1ey--ElXdCkZ474FNozO1r-uec9Q87Cd227yUX0BHUdtgND09IOFosEl1epIM434m7Fjx0POqhypOHTEbHNE9cEhQJmFePwe5eDRvMi_dPVhbiduFoFuAjPu4zNcAxvDWcVFf0kM4T-ytTK0kiSh0zcW0KzIg_3M8iXmnp6DbDE"
}

Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed",
    "status": 401
}

Authorized API Calls

Add Authorization header with value Bearer ACCESS_TOKEN_STRING where ACCESS_TOKEN_STRING is the received access_token from /api/app/oauth/access_token endpoint.

Test Request

GET /api/app/test HTTP/1.1
Host: yourshopname.com
Authorization: Bearer ACCESS_TOKEN_STRING
Accept-Encoding: gzip

Test Success Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "test": "OK"
}

Error Response for Invalid Access Token

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Encoding: br

{
    "error": "access_denied",
    "error_description": "The resource owner or authorization server denied the request.",
    "status": 400
}

Error Response for Expired Token:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Encoding: br

{
  "error": "invalid_token",
  "error_description": "The access token expired"
}