Authorization and authentication


   

General description

To address RESTful service of OZON.RU, URL https://api.ozon.ru (SSL) or http://api.ozon.ru (not recommended due to security reasons) shall be used.

Each client (and further, each application) of the service is given 2 parameters — ApplicationId (application name) and secret key. ApplicationId is used for user identification in the system and the secret key - for signature authentication of the application.

Token system is introduced so that signature, authorization, etc. is not needed to use the system.

A token is a temporary key to the service you need access to, it can be received by application through authorization service. A token is the evidence that the application is authorized and has access to the chosen service. The token is valid for a limited time period, but with each successful request (or even request not in quota) its validity is prolonged.

So the technique is rather simple —it is necessary to receive a token and later use it with the service needed.

How to receive a token

Send request to AuthAPI. The request is as follows:

GET https://api.ozon.ru/auth/token/[SERVICE_NAME]

For example:

https://api.ozon.ru/auth/token/merchants

Also, send ApplicationId, it can be implemented through query string:

https://api.ozon.ru/auth/token/merchants?applicationid=superapp

Or, this parameter can be sent through request headers (example for cUrl):

curl -X GET -H "accept:application/json" -H "x-applicationid:superapp" https://api.ozon.ru/auth/token/merchants

AuthAPI has to make sure that the application is the right one, so it is necessary to sign the request. To sign the request it is necessary to calculate SHA1-HMAC signature, where the secret key of the application shall be the key and the value for signature shall be the URL path part:

/auth/token/merchants?applicationid=superapp

If ApplicationId is sent by headers, it is necessary to write only:

/auth/token/merchants

After that the signature shall be added to query string:

https://api.ozon.ru/auth/token/merchants?applicationid=superapp&sign=d67a1dafd70d70833211a715e54d2241b0744220

Or, the signature may be sent with request header:

curl -X GET -H "accept:application/json" -H "x-applicationid:superapp" -H "x-sign:d67a1dafd70d70833211a715e54d2241b0744220" https://api.ozon.ru/auth/token/merchants

In response, the following structure shall be sent, containing your token and its lifetime in seconds (example for JSON):

{ "token": "9895DDA48379484ABC51A4B193CDAE04", "expiration": 600 }

Errors while getting a token

The following errors may be returned:

  • 401 Bad sign - signature not valid
  • 404 Api Not Found - request for token to non-existing API
  • 400 Api Not Set - API to which the token is requested was not specified
  • 400 No Application Id - ApplicationId not indicated
  • 409 Token Already Acquiring - token is being sent
  • 403 Auth Failed - attempt failed. Application is not authorized for specified service.

Also, standard errors 404/500/502 are possible.

How to use the token

Once you got a token, you can address the service you need. Indicate ApplicationId (as in getting a token – in header or query string) and your token in request:

https://api.ozon.ru/merchants/files?applicationid=superapp&token=9895DDA48379484ABC51A4B193CDAE04

or

curl -H "accept:application/json" -H "x-applicationid:superapp" -H "x-token:9895DDA48379484ABC51A4B193CDAE04" https://api.ozon.ru/merchants/files

Errors while addressing service with a token

Errors that can be indicated in response:

  • 401 Ask for token - Invalid token/token does not exist
  • 404 Api Not Found - token request to non-existing API
  • 400 Api Not Set - API to which the token is requested was not specified
  • 401 Token required - token not specified
  • 429 Quota exceed - Quota exceeded, please wait.

Also, standard errors are possible 404/500/502. In case of business error it will be added to errors array (see API errors format (structure) of “500 Server error”.