Авторизация и аутентификация


   

Общее описание

Для обращения к RESTful-сервису OZON.RU следует использовать URL https://api.ozon.ru (SSL) или http://api.ozon.ru (не рекомендуется из соображений безопасности).

Каждому клиенту (в дальнейшем - приложению) сервисов выдается 2 парамера - ApplicationId (название приложения) и секретный ключ. ApplicationId используется для идентификации приложения в системе, секретный ключ - для аутентификации приложения через проверку подписи.

Чтобы каждый раз не проверять подпись, авторизацию и т.д., введен механизм токенов.

Токен - это временный ключ к требуемому сервису, полученый приложением через сервис авторизации. Токен говорит о том, что приложение уже прошло авторизацию и имеет право доступа к выбранному сервису. Токены живут ограниченное время, но с каждым успешным запросом (или даже запросом, не прошедшим квотирование) пролонгируются.

Итак, механизм прост - необходимо получить токен и дальше использовать его с нужным сервисом.

Получение токена

Необходимо выполнить запрос к AuthAPI. Запрос составляется следующим образом:

GET https://api.ozon.ru/auth/token/[ИМЯ_СЕРВИСА]

Например:

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

Также необходимо передать ApplicationId. Это можно сделать через query string:

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

Либо можно передать этот параметр через заголовки запроса (пример для cUrl):

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

AuthAPI необходимо убедиться, что приложение именно то, за которое он себя выдает, поэтому необходимо подписать запрос. Чтобы это сделать, необходимо рассчитать SHA1-HMAC подпись, где ключом будет секретный ключ приложения, а значением на подпись - path-часть URL:

/auth/token/merchants?applicationid=superapp

Если ApplicationId передан через заголовки, то подписать стоит только:

/auth/token/merchants

После чего подпись нужно добавить к querystring:

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

Или подпись можно передать через заголовок запроса:

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

В ответ придет следующая структура с токеном и время его жизни в секундах (пример для JSON):

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

Ошибки при получении токена

Могут быть возвращены следующие ошибки:

  • 401 Bad sign - подпись неверна
  • 404 Api Not Found - запрос на токен к несуществующему API
  • 400 Api Not Set - не задан API, к которому требуется получить токен
  • 400 No Application Id - не указан ApplicationId
  • 409 Token Already Acquiring - токен уже в процесс получения
  • 403 Auth Failed - попытка не удалась. Приложение не авторизовано для указанного сервиса

А также стандартные ошибки 404/500/502.

Планируемые изменения

В скором времени будет введено требование указания timestamp-а в запросе на получение токена. Также будет введена OAuth2-авторизация, в рамках которой ответ на запрос токена будет приходить на указанный владельцем приложения URL (callback).

Работа с токеном

Имея токен, можно обращаться к требуемому сервису. Для обращения необходимо указать ApplicationId (как в случае с получением токена - в заголовке или в query string) и указать токен:

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

или

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

Ошибки при работе с сервисом с помощью токена

Могут быть возвращены следующие ошибки:

  • 401 Ask for token - Указан неверный токен/токена уже нет
  • 404 Api Not Found - запрос на токен к несуществующему API
  • 400 Api Not Set - не задан API, к которому требуется получить токен
  • 401 Token required - не указан токен
  • 429 Quota exceed - Квота выработана. Надо подождать.

А также стандартные ошибки 404/500/502. В случае бизнес-ошибки она обязательно будет добавлена в массив errors (см. Формат (структура) ошибок API) ошибки 500 Server error.