Введение
Freedom ID — это единый аккаунт для входа в сервисы группы компаний Freedom, а также на сторонние сайты и приложения, поддерживающие такую авторизацию.
Данное API позволяет настроить единую авторизацию на вашем сайте либо в мобильном приложении.
API Freedom ID поможет упростить взаимодействие с вашим сайтом:
  • Единая авторизация. Пользователи могут войти на ваш сайт или в приложение, используя существующий аккаунт Freedom ID. Это избавляет их от необходимости регистрировать новую учетную запись и заполнять дополнительные формы.
  • Передача актуальных данных. С разрешения пользователя вы получите необходимые данные для создания или обновления аккаунта на вашем сервисе.
  • Веб-авторизация. посетители могут войти на ваш сайт, используя виджет или кнопку авторизации Freedom ID.
  • Мобильная авторизация: через SDK для мобильных устройств можно настроить мгновенную авторизацию. Если пользователь уже вошел в свой аккаунт Freedom ID на устройстве, интерфейс автоматически отобразит его имя и аккаунт, предлагая продолжить авторизацию.
Как это работает?
  1. После успешной интеграции на странице авторизации вашего сервиса пользователь выбирает вход через аккаунт Freedom ID.

Страница авторизации партнерского сервиса

2. Сервис, интегрированный с API Freedom ID, перенаправляет пользователя в окно авторизации Freedom ID. Там пользователь подтверждает вход и разрешает доступ к своим данным.
3. Получение токенов. После успешной авторизации ваш сервис получает authorization_code через указанный redirect_uri. Затем необходимо отправить запрос для обмена authorization_code на токены пользователя и сохранить их в вашей системе.
4. Получение данных пользователя. Сервис отправляет запрос к API FID, указывая полученный client_access_token, и получает данные пользователя. Полученные данные используются для авторизации и заведения учетной записи в вашей базе пользователей.
5. Таким образом пользователь FID получает аккаунт в вашем приложении, не заводя новую учетную запись.
6. Запрос профиля клиента. Для получения дополнительных данных о пользователе отправьте запрос "Профиль клиента". При этом необходимо предварительное подтверждение от пользователя на предоставление доступа к его профилю.
Подключение к API Freedom ID
Регистрация Партнерского сервиса в FID
Для работы с API Freedom ID партнерскому сервису требуются Логин и Пароль. Получить эти данные можно обратившись в группу поддержки продукта по электронному адресу support@freedompay.kz. В письме должны быть указаны следующие данные:
  1. Название вашего сервиса
  2. Платформы на которых работает ваше приложение (веб, IOS. Android)
  3. Контактные данные ответственных лиц вашего сервиса
Пример письма:
Тема: Запрос на подключение сервиса к API Freedom ID
Уважаемая команда поддержки Freedom ID,
Меня зовут [Ваше имя], я представляю платформу ТОО «Арбуз». Мы хотели бы подключить наш сервис к API Freedom ID для обеспечения единой авторизации пользователей.
Для получения логина и пароля для интеграции предоставляем необходимую информацию:
  1. Название сервиса: ТОО «Арбуз»
  2. Платформы: веб, iOS, Android
  3. Контактные данные ответственных лиц:
  • Имя: [ФИО ответственного лица]
  • Должность: [Должность]
  • Email: [Email ответственного лица]
  • Телефон: [Номер телефона]
Генерация ссылки на форму аутентификации пользователя
Этот метод используется для генерации ссылки, на которую будет перенаправлен пользователь для аутентификации через Freedom ID. Приложение отправляет запрос с необходимыми параметрами, и в ответ получает URL для перенаправления.
Запрос:

Endpoint:

POST https://passport.freedompay.kz/api/v1/oauth/authorize
Заголовки:
Authorization: Basic base64encode("{CLIENT_ID}:{CLIENT_SECRET}")
Параметры тела запроса:
{
  "redirect_uri": "https://example.com/login",
  "grants": [
    "read.email",
    "read.phone",
    "read.date_of_birth",
    "read.firstname",
    "read.lastname",
    "read.gender",
    "read.nationality",
    "read.profile",
    "read.country"
  ]
}
Ответ:
{
  "redirect_uri": "https://passport.freedompay.kz/login?track_id=ac22c50c-22c7-4aeb-9160-e59b735f9c44&expire_at=1727246098"
}
Ответ в случае ошибки:
{
    "error": {
        "message": "Error validating transmitted data.",
        "errors": {
            "grants": [
                "The Grants field is required."
            ]
        }
    }
}
Получение токена по коду авторизации
Описание:
Если пользователь согласился предоставить запрашиваемые права, Freedom ID перенаправляет аутентифицированного пользователя на страницу redirect_uri из запроса партнёра и передаёт authorization_code дополнительным параметром (https://example.com/login?authorization_code=XYZ). Полученный authorization_code связан с партнёром и является одноразовым кодом доступа. Данный код необходимо обменять на access_token и refresh_token для дальнейшей работы.

Запрос:

Endpoint:
POST https://passport.freedompay.kz/api/v1/oauth/token

Заголовок:
Authorization: Basic base64encode("{CLIENT_ID}:{CLIENT_SECRET}")
Параметры тела запроса:
{
  "authorization_code": "your_authorization_code"
}
Ответ:
{
  "access_token": "your_access_token",
  "refresh_token": "your_refresh_token",
  "access_expire_at": "2024-10-02T10:52:21.000000Z",
  "refresh_expire_at": "2024-10-25T10:52:21.000000Z"
}
Ответ в случае ошибки:
{
    "error": {
        "message": "Invalid authorization_code.",
        "code": 100101
    }
}
Получение данных пользователя
Описание:

Этот метод позволяет приложению получить информацию о пользователе, используя действующий access_token. В ответ возвращаются данные, которые приложение может использовать для персонализации пользовательского интерфейса или других целей.

Запрос:

Endpoint:

GET https://passport.freedompay.kz/api/v1/oauth/get-data
Заголовок:
Authorization: Beareer {client_access_token}
Ответ:
{
  "id": "user_id",
  "firstname": "user_firstname",
  "lastname": "user_lastname",
  "date_of_birth": "user_date_of_birth",
  ...
}
Обновление токенов
Описание:

Этот метод используется для обновления истекшего access_token с помощью refresh_token. Если access_token истек, приложение может использовать refresh_token для получения нового набора токенов.

Запрос:
Endpoint:
PATCH https://passport.freedompay.kz/api/v1/oauth/token
Заголовок:
Authorization: Bearer refresh_token
Ответ:
{
  "access_token": "new_access_token",
  "refresh_token": "new_refresh_token",
  "access_expire_at": "new_expiration_time",
  "refresh_expire_at": "new_expiration_time"
}
Запрос Профиля клиента
Описание:

Этот метод используется для получения персональных и иных аналитических данных клиента (пользователя). Перед отправкой данного запроса необходимо предварительно отправить запрос на разрешение read.profile в грантах на этапе генерации ссылки для аутентификации. Если физическое лицо дало согласие на доступ, и разрешение активно, запрос на получение данных профиля отправляется в очередь на обработку.

Запрос:
Endpoint:
POST https://passport.freedompay.kz/api/v1/oauth/get-profile
Заголовок:
Authorization: Beareer {client_access_token}
Параметры тела запроса:
{
  "request_id": "UUID",
  "created_at": "2024-10-17T12:00:00Z"
}
Ответ:
  • Код 200 OK
{
  "request_id": "string",
  "status": "accepted",
  "freedom_id": "UUID"
}
Коды ответов:
  • 200 OK: Запрос успешно принят.
  • 422 Unprocessable Content : Неверный формат данных или отсутствие обязательных параметров.
  • 500 Internal Server Error: Ошибка на стороне сервера.
Статус запроса профиля клиента
Описание:

Запрос на получение статуса запроса профиля клиента.

Запрос:
Endpoint:
GET https://passport.freedompay.kz/api/v1/oauth/get-profile/status
Заголовок:
Authorization: Beareer {client_access_token}
Тело запроса:
{
  "request_id": "string"
}
Ответ:
  • Код 200 OK
{
  "request_id": "string",
  "status": "completed",
  "freedom_id": "UUID",
  "profile": {
    ...
  },
  "datetime": "2024-10-17T12:10:00Z"
}
Коды ответов:
  • 200 OK: Статус успешно получен.
  • 500 Internal Server Error: Ошибка на стороне сервера.
Справочники
Справочник кодов доступа к данным пользователя
Справочник параметров данных пользователя
Справочник кодов ошибок