Введение
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: Ошибка на стороне сервера.
Справочники
Справочник кодов доступа к данным пользователя
Справочник параметров данных пользователя
Справочник кодов ошибок
Freedom ID SDK Android

Introduction
Welcome to the Freedom ID SDK integration guide! This guide will help you smoothly integrate the Freedom ID SDK into your Android app, enabling secure authentication and user data permission management within the Freedom Holding ecosystem. Freedom ID serves as a single point of entry for users, ensuring top-level security and privacy while managing data permissions and accessing multiple services.
The Freedom ID SDK is available for both Android (API level 24 and above) and iOS platforms. This guide specifically covers the Android platform. Let's get started! 🚀
Getting Started
Prerequisites
Before you begin integrating the Freedom ID SDK into your Android app, ensure you have the following:
-An Android app project with a minimum API level of 24.
-An API key provided by Freedom Pay.
-The Freedom ID SDK AAR file provided by Freedom Pay
[!info] How to get API KEY and AAR?In order to get your API KEY and AAR you need to contact Freedom Pay providing the following data:
-ApplicationID
-Signing Fingerprint from your Google Play Account
Installation Instructions
Automatically
You can add the AAR via Project Structure's Dependency Tab as specified in the official docs here
.
Manually
Alternatively, you can use this method:
1.Place the freedom-id-sdk.aar in the libs directory of your app module. If the libs directory doesn’t exist, create it at the root of your app module (e.g., app/libs)
2.Add the AAR file as a dependency in the build.gradle file of your app module and settings.gradle
// build.gradle
dependencies {
    implementation files('libs/freedom-id-sdk.aar')
}
//settings.gradle
repositories {
flatDir {
             dirs("libs")
       }
}
3. Sync the project
Usage
Initialize the SDK
To initialize the Freedom ID SDK, call the create method of the FreedomID class. This method requires two parameters:
- The API key provided by Freedom ID.
- The application context.
val apiKey = YOUR_API_KEY
val context = applicationContext
val freedomID = FreedomID.create(apiKey, context)
Authorize a User
To authorize a user, call the authorize method of the FreedomID class. This method initiates the authorization flow. The authorize method takes three parameters:
  1. The FragmentManager of the activity or fragment where the authorization flow will be displayed.
  2. An array of DataGrants that the user needs to grant.
  3. A callback function that will be invoked when the authorization flow completes.
The authorization process returns an AuthResult object, which can be either:
  • Success: Contains a GrantedProfile object.
  • Error: Specifies the type of error that occurred.
Here's an example:
val fragmentManager = supportFragmentManager
val dataPermissions = arrayOf(DataGrants.READ_FIRSTNAME, DataPermissions.READ_LASTNAME)

freedomID.authorize(fragmentManager, dataPermissions) { authResult ->
    when(authResult) {
        is AuthResult.Success -> {
            // Authorization successful 🚀
            val profile = authResult.profile
            // Do something with the profile
        }
        is AuthResult.Error -> {
            // Authorization failed ⛔
            // Handle the error accordingly
        }
    }
}
Clear the SDK
To clear the SDK, call the clear method of the FreedomID class.
This method clears the SDK's internal state and releases any resources used during the authorization process.
freedomID.clear()
Authorization Flow
App Initialization
When the user opens the app, it automatically checks if there are any accounts tied to their device.

Account Check
- If an account exists: The user is navigated directly to the Home Screen, where their account(s) are displayed.
- If no account exists: The user is taken to the Screen to log in. After successful authentication, the user is redirected to the Home.

Authentication Screen Interaction
The user can log in using any of these methods:
- Entering their phone number and receiving an OTP code via SMS.
- Entering their email and password as credentials.
- Entering their phone number and password as credentials.
Optionally, users can enable 2FA for additional security. To enable 2FA, they need to manage their settings in their Freedom ID account on the web at https://passport.freedompay.kz

Home Screen Interaction
- On the Home screen, users see their account(s).
- Users select an account for which they need to request data permissions and apply fingerprint

Request for Permissions
- After selecting an account, the app presents the Permissions Request Screen.
- Users review the requested permissions (e.g., access to specific user data).

User Decision
- Permissions Granted ✅: The host app is granted the requested permissions.
- Permissions Denied ❌: The app returns to the Home Screen or informs the user that permissions are needed to proceed.

Completion
Once permissions are granted, the user is notified of successful authorization, and the SDK communicates the result back to the host app.
Data Structures


DataGrants Structure

General Description
This enum represents a set of permissions that a host application can request from the SDK to grant access to specific profile data.
Each constant corresponds to a particular piece of user information, allowing the host app to selectively request access based on its needs.
Below is a table describing the different DataGrants available in the Freedom ID SDK:
GrantedProfile Structure
General Description
The GrantedProfile data class represents a user's profile information that is accessible after the required read permissions have been granted by the host application via the SDK.
data class GrantedProfile(
    val id: String,
    val identifier: String,
    val email: String,
    val emails: List<String>,
    val nationality: String,
    val phone: String,
    val phones: List<String>,
    val dateOfBirth: String,
    val firstname: String,
    val lastname: String,
    val patronymic: String?,
    val gender: String,
    val country: String
)
AuthResult Structure
General Description
The AuthResult is a sealed interface representing the result of an authentication process. It has two primary branches:
  1. Success: Indicates a successful authentication with the granted user profile as its payload.
  2. Error: Represents various types of errors that may occur during the authentication process. Each error type is modeled either as :
a. A data object for static cases
b. Or a data class for cases requiring additional information.
Table1: AuthResult
Table 2: Error (Subtype of AuthResult)
TransmissionErrors Structure
General Description
The TransmissionErrors enum defines a set of possible errors that can occur during the transmission of requests in an authentication or communication process.
Each error represents a specific issue related to the request's structure, identification, application integrity, or the process of sending and receiving requests.
Table: TransmissionErrors
NetworkError Structure
General Description
The NetworkError sealed interface defines a set of possible errors that may occur during network operations.
Each subtype of NetworkError represents a specific issue, such as connection failures, stream interruptions, or problems with request/response handling.
Table: NetworkError
Support

If you have questions or need help integrating the SDK, feel free to reach out! 👋
Email: support@freedompay.kz
Freedom ID SDK iOS

Introduction
Welcome to the Freedom ID SDK integration guide! This guide will help you smoothly integrate the Freedom ID SDK into your iOS app, enabling secure authentication and user data permission management within the Freedom Holding ecosystem. Freedom ID serves as a single point of entry for users, ensuring top-level security and privacy while managing data permissions and accessing multiple services.
The Freedom ID SDK is available for both Android (API level 24 and above) and iOS (12 and above) platforms. This guide specifically covers the iOS platform. Let’s get started! 🚀
Getting Started
Prerequisites
Before you begin integrating the Freedom ID SDK into your iOS app, ensure you have the following:
  • An iOS app project with a minimum iOS 12 support.
  • An API key provided by Freedom Pay.
  • The Freedom ID SDK .xcframework file provided by Freedom Pay
[!info] How to get API KEY and .xcframework file?
In order to get your API KEY and .xcframework you need to contact Freedom Pay providing the following data:
  • Bundle Identifier
  • Team ID from Apple Developer Concole
Installation Instructions
  1. Open Project Settings in Xcode
  2. Select required Target
  3. Go to General Tab and in Frameworks, Libraries, and Embedded Content and click +
  4. Select Add Other... and then Add files...
  5. Choose FreedomID.xcframework
  6. Now you can import SDK and use it further
import FreedomID
Usage
Initialize the SDK
To initialize the Freedom ID SDK, call the create method of the FreedomID class. This method requires one parameter:
  • The API key provided by Freedom ID.
let freedomID = FreedomID.create(apiKey: "your_api_key")
Authorize a User
To authorize a user, call the authorize method of the FreedomID class. This method initiates the authorization flow.
The authorize method takes three parameters:
  1. The UIViewController of your app where the authorization flow will be displayed.
  2. An array of DataGrants that the user needs to grant.
  3. A callback function that will be invoked when the authorization flow completes.
The authorization process returns an Result object, which can be either:
  • .success: Contains a GrantedProfile object.
  • .failure: Specifies the type of error that occurred.
Here’s an example:
let grants = [DataGrants.readFirstname, DataGrants.readLastname]

freedomID.authorize(viewController: self, dataGrants: grants) { (result: Result<GrantedProfile, AuthError>) in
    switch result {
    case .success(let grantedProfile):
        // Authorization successful 🚀
        let fullname = grantedProfile.firstname + " " + grantedProfile.lastname
        // Do something with the grantedProfile
    case .failure(let error):
        // Authorization failed ⛔
        // Handle the error accordingly
        break;
    }
}
Clear the SDK
To clear the SDK, call the clear method of the FreedomID class.
This method clears the SDK’s internal state and releases any resources used during the authorization process.
FreedomID.clear()
Authorization Flow
App Initialization
When the user opens the app, it automatically checks if there are any accounts tied to their device.
Account Check
  • If an account exists: The user is navigated directly to the Home Screen, where their account(s) are displayed.
  • If no account exists: The user is taken to the Authentication Screen to log in. After successful authentication, the user is redirected to the Home Screen.

Authentication Screen Interaction
The user can log in using any of these methods:
  • Entering their phone number and receiving an OTP code via SMS.
  • Entering their email and password as credentials.
  • Entering their phone number and password as credentials.
Optionally, users can enable 2FA for additional security. To enable 2FA, they need to manage their settings in their Freedom ID account on the web at https://passport.freedompay.kz

Home Screen Interaction
  • On the Home screen, users see their account(s).
  • Users select an account for which they need to request data permissions and apply fingerprint
Request for Permissions
  • After selecting an account, the app presents the Permissions Request Screen.
  • Users review the requested permissions (e.g., access to specific user data).

User Decision
  • Permissions Granted ✅: The host app is granted the requested permissions.
  • Permissions Denied ❌: The app returns to the Home Screen or informs the user that permissions are needed to proceed.

Completion
Once permissions are granted, the user is notified of successful authorization, and the SDK communicates the result back to the host app.
Data Structures


DataGrants Structure

General Description
This enum represents a set of permissions that a host application can request from the SDK to grant access to specific profile data.
Each constant corresponds to a particular piece of user information, allowing the host app to selectively request access based on its needs.
Below is a table describing the different DataGrants available in the Freedom ID SDK:
GrantedProfile Structure
General Description
The GrantedProfile data class represents a user’s profile information that is accessible after the required read permissions have been granted by the host application via the SDK.
public struct GrantedProfile: Codable {
    public var id: String = ""
    public var email: String = ""
    public var emails: [String] = [ ]
    public var nationality: String = ""
    public var phone: String = ""
    public var phones: [String] = [ ]
    public var dateOfBirth: String = ""
    public var firstname: String = ""
    public var lastname: String = ""
    public var patronymic: String? = ""
    public var gender: String = ""
    public var country: String = ""

}
Result Structure
General Description
The Result representing the result of an authentication process. It has two primary branches:
  1. .success: Indicates a successful authentication with the granted user profile as its payload.
  2. .failure: Represents various types of errors that may occur during the authentication process. Each error type is modeled either as :
a. An enum static cases
b. Or enum with associated values for cases requiring additional information.
Table1: Result
Table 2: .failure contents
TransmissionErrors Structure
General Description
The TransmissionErrors enum defines a set of possible errors that can occur during the transmission of requests in an authentication or communication process.
Each error represents a specific issue related to the request’s structure, identification, application integrity, or the process of sending and receiving requests.
Table: TransmissionErrors
NetworkError Structure
General Description
The NetworkError enum defines a set of possible errors that may occur during network operations.
Each error represents a specific issue, such as connection failures, stream interruptions, or problems with request/response handling.
Table: NetworkError
Support

If you have questions or need help integrating the SDK, feel free to reach out! 👋
Email: support@freedompay.kz