Получение и обновление токенов

Обмен кода авторизации на токены и обновление токенов в Флида ID.

Аутентификация

Token endpoint поддерживает два способа аутентификации клиента:

client_secret_basic (рекомендуемый). Передайте client_id и client_secret через двоеточие в заголовке HTTP Basic Authentication: Authorization: Basic BASE64(client_id:client_secret).
client_secret_post. Передайте client_id и client_secret в теле запроса.

Не используйте оба способа одновременно и никогда не передавайте Client Secret из браузера или мобильного клиента. Выполняйте обмен токенов на защищенном сервере проекта.

Получение токенов по коду авторизации

После успешной авторизации обменяйте одноразовый code на токены:

POST https://api.flida.ru/oidc/token
Content-Type: application/x-www-form-urlencoded

Параметры тела запроса

Параметр	Описание
`grant_type`	Обязательный. Передайте `authorization_code`.
`code`	Обязательный. Код из успешного ответа авторизации.
`code_verifier`	Обязательный. Исходный `code_verifier`, для которого был сформирован `code_challenge`.
`redirect_uri`	Обязательный. Тот же адрес, который использовался в запросе авторизации. Пример: `https://myapp.ru/callback`
`client_id`	Обязательный для `client_secret_post`. При `client_secret_basic` не передавайте его в теле.
`client_secret`	Обязательный для `client_secret_post`. При `client_secret_basic` не передавайте его в теле.

Пример с `client_secret_basic`

POST /oidc/token HTTP/1.1
Host: api.flida.ru
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MDE5ZDlhOGEtN2Y4Yi03ZjU0LTlkNGUtNGE5ZWNjOWZjNjA5Om15X3N1cGVyX3NlY3JldA==

grant_type=authorization_code&code=gTqEcwBiRN3VE...&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&redirect_uri=https%3A%2F%2Fmyapp.ru%2Fcallback

Пример с `client_secret_post`

POST /oidc/token HTTP/1.1
Host: api.flida.ru
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=gTqEcwBiRN3VE...&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&redirect_uri=https%3A%2F%2Fmyapp.ru%2Fcallback&client_id=019d9a8a-7f8b-7f54-9d4e-4a9ecc9fc609&client_secret=my_super_secret

Успешный ответ

Сервер вернет 200 OK и JSON:

{
  "access_token": "jb_R5GUySe03A429pTEGh5AmovonbN0k2ArE-8r2k04",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleTEifQ...",
  "refresh_token": "dpz7WtUyZ2w-5_9WnDCkm4jWahwP0RJ9LrbUQ4PP7vQ",
  "token_type": "Bearer"
}

Параметр	Тип	Описание
`access_token`	`string`	Токен для запроса информации о пользователе.
`expires_in`	`int`	Срок действия `access_token` в секундах.
`id_token`	`string`	Подписанный JWT с идентификационными данными пользователя.
`refresh_token`	`string`	Токен для обновления набора токенов. Срок действия — 365 дней.
`token_type`	`string`	Схема авторизации. Всегда `Bearer`.

ID-токен

id_token — JWT, подписанный алгоритмом RS256. Он содержит стандартные служебные поля и данные из разрешенных пользователем областей доступа. Срок действия ID-токена — 30 дней.

Для получения актуальных данных профиля используйте access_token и UserInfo endpoint.

Пример payload

{
  "iss": "https://api.flida.ru",
  "sub": "v1.ffd02a9186905c46c21a2f671ec665470c9533660658bcf4e610369a57155658",
  "aud": "019d9a8a-7f8b-7f54-9d4e-4a9ecc9fc609",
  "exp": 1716588400,
  "iat": 1713996400,
  "date_of_birth": "2001-01-02",
  "email": "test@test.ru",
  "email_verified": true,
  "given_name": "Александр",
  "family_name": "Пушкин",
  "middle_name": "Сергеевич",
  "nickname": "Пушкин А. С.",
  "phone_number": "+79107777777",
  "phone_number_verified": true,
  "sex": "male"
}

Поле	Описание
`iss`	Идентификатор издателя. Должен быть равен `https://api.flida.ru`.
`sub`	Попарный идентификатор пользователя в организации, которой принадлежит проект. Два проекта одной организации получают одинаковый `sub` для одного пользователя.
`aud`	Идентификатор получателя. Должен совпадать с `client_id` вашего проекта.
`exp`	Время окончания действия токена в формате временной метки Unix.
`iat`	Время выпуска токена в формате временной метки Unix.
`given_name`	Область доступа `name`. Имя.
`family_name`	Область доступа `name`. Фамилия.
`middle_name`	Область доступа `name`. Отчество; может отсутствовать.
`nickname`	Область доступа `nickname`. Отображаемое имя.
`date_of_birth`	Область доступа `date_of_birth`. Дата рождения в формате `YYYY-MM-DD`.
`sex`	Область доступа `sex`. Значение `female` или `male`.
`phone_number`	Область доступа `phone`. Номер телефона.
`phone_number_verified`	Область доступа `phone`. Признак подтверждения номера телефона.
`email`	Область доступа `email`. Адрес электронной почты.
`email_verified`	Область доступа `email`. Признак подтверждения адреса электронной почты.

Проверка ID-токена

Проверяйте ID-токен на сервере проекта с помощью стандартной OIDC-библиотеки:

Разрешайте только алгоритм RS256.
Получите открытый ключ по kid из актуального JWKS и проверьте подпись.
Проверьте точное значение iss: https://api.flida.ru.
Убедитесь, что aud совпадает с client_id проекта.
Отклоните токен, если срок exp истек.

Не используйте данные ID-токена до завершения всех проверок.

Обновление токенов

Когда access_token истечет, отправьте refresh_token на тот же endpoint. Требования к аутентификации проекта не меняются.

Параметры тела запроса

Параметр	Описание
`grant_type`	Обязательный. Передайте `refresh_token`.
`refresh_token`	Обязательный. Refresh-токен из предыдущего успешного ответа.
`client_id`	Обязательный для `client_secret_post`. При `client_secret_basic` не передавайте его в теле.
`client_secret`	Обязательный для `client_secret_post`. При `client_secret_basic` не передавайте его в теле.

Пример с `client_secret_basic`

POST /oidc/token HTTP/1.1
Host: api.flida.ru
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MDE5ZDlhOGEtN2Y4Yi03ZjU0LTlkNGUtNGE5ZWNjOWZjNjA5Om15X3N1cGVyX3NlY3JldA==

grant_type=refresh_token&refresh_token=dpz7WtUyZ2w-5_9WnDCkm4jWahwP0RJ9LrbUQ4PP7vQ

Пример с `client_secret_post`

POST /oidc/token HTTP/1.1
Host: api.flida.ru
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=dpz7WtUyZ2w-5_9WnDCkm4jWahwP0RJ9LrbUQ4PP7vQ&client_id=019d9a8a-7f8b-7f54-9d4e-4a9ecc9fc609&client_secret=my_super_secret

При успехе сервер вернет новый access_token, id_token и refresh_token. Сохраните новый refresh-токен и больше не используйте предыдущий.

Ошибки получения и обновления токенов

Ошибка возвращается в JSON:

{
  "error": "invalid_grant",
  "error_description": "invalid authorization grant"
}

HTTP-статус	Ошибка	Что означает	Что делать проекту
`400`	`invalid_request`	Отсутствует обязательный параметр, параметр имеет неверный формат или одновременно использованы Basic и POST-аутентификация.	Исправить запрос. Не повторять его без изменений.
`400`	`invalid_grant`	Код или refresh-токен не найден, истек, уже использован либо не совпадают PKCE, `client_id` или `redirect_uri`.	Для кода начать авторизацию заново; для refresh-токена запросить повторный вход пользователя.
`400` или `401`	`invalid_client`	Не удалось определить или аутентифицировать проект.	Проверить `client_id`, `client_secret` и выбранный способ аутентификации.
`400`	`unauthorized_client`	Проект не активирован.	Обратиться в поддержку.
`400`	`unsupported_grant_type`	Передано неподдерживаемое значение `grant_type`.	Использовать `authorization_code` или `refresh_token`.
`500`	`server_error`	Внутренняя ошибка Флида ID.	Повторить запрос позже.

При 401 invalid_client и использовании HTTP Basic Authentication ответ также содержит WWW-Authenticate: Basic realm="oidc".

Получение и обновление токенов

На этой странице