Introduction

Freedom ID is a unified account system for accessing services provided by the Freedom Group of Companies and supported third-party websites or applications.
This API enables configuring a single sign-on experience for your website or mobile application.

The Freedom ID API offers the following benefits:

Unified Authorization:
Users can log into your website or application using their existing Freedom ID account, removing the need for new account registrations and forms.

Data Transfer:
With user consent, necessary data can be retrieved for account creation or updates.

Web Authorization:
Allows login via Freedom ID widgets or buttons on your site.

Mobile Authorization:
Integrates SDKs for mobile devices to facilitate seamless login if users are already signed into Freedom ID on their devices.

How It Works

Authorization Process

Once integrated, your service’s login page will display an option to log in via Freedom ID.

Users selecting this option are redirected to the Freedom ID authorization page to approve login and data sharing.

Token Exchange

Upon successful authorization, your service receives an authorization_code via the specified redirect_uri.

This code must be exchanged for access_token and refresh_token using a token request.

Retrieving User Data

Using the client_access_token, send a request to the Freedom ID API to obtain user data.

This data can then be used to authenticate and register the user in your system without requiring a new account.

Client Profile Request

To retrieve additional user profile information, submit a "Client Profile" request.

Prior user consent is required for profile access.

API Integration Steps

Partner Service Registration with Freedom ID

To work with the Freedom ID API, a partner service needs credentials (Login and Password). These can be obtained by contacting the product support team via email: support@freedompay.kg.

Your email should include:

Service Name

Platforms (e.g., web, iOS, Android)

Contact Information of responsible personnel

Example Email

Subject: Request for Service Integration with Freedom ID API  

Dear Freedom ID Support Team,  

My name is [Your Name], representing the platform [Your Company Name]. We aim to integrate our service with the Freedom ID API for unified user authorization.  

Service Name: [Your Service Name]  
Platforms: [Platform List]  
Contact Details:  
- Name: [Responsible Person's Name]  
- Position: [Position]  
- Email: [Email Address]  
- Phone: [Phone Number]

User Data Access Codes

Parameter	Description
`date_of_birth`	User's date of birth (e.g., `read.date_of_birth`).
`firstname`	User's first name (e.g., `read.firstname`).
`lastname`	User's last name (e.g., `read.lastname`).
`patronymic`	User's patronymic (e.g., `read.patronymic`).
`country`	User's citizenship (e.g., `read.country`).
`nationality`	User's nationality (e.g., `read.nationality`).
`gender`	User's gender (e.g., `read.gender`).
`identifier`	User's identifier (e.g., `read.identifier`).
`phone`	User's primary phone number (e.g., `read.phone`).
`email`	User's primary email address (e.g., `read.email`).
`phones`	Additional phone numbers (e.g., `read.phones`).
`emails`	Additional email addresses (e.g., `read.emails`).
`profile`	Extended profile data (e.g., `read.profile`).

User Data Parameters

Parameter	Type	Description
`date_of_birth`	string (YYYY-MM-DD)	User's date of birth.
`firstname`	string	User's first name.
`lastname`	string	User's last name.
`patronymic`	null or string	User's patronymic.
`country`	string	User's country.
`nationality`	string	User's nationality.
`gender`	string	User's gender.
`identifier`	string	User's identifier.
`phone`	string	User's primary phone number.
`email`	string	User's primary email address.
`phones`	array of strings	Additional phone numbers.
`emails`	array of strings	Additional email addresses.

Link

This method generates a link to redirect users to the Freedom ID authentication page. The service sends a request specifying:

The URL where the user will be redirected after successful authentication (redirect_uri).

An array of data types required by the service from the user (grants).

In response, the service receives a generated link to redirect the user for authentication.

Token

When a user consents to provide the requested access rights, Freedom ID redirects the user to the specified redirect_uri with an appended authorization_code parameter. This one-time code must be exchanged for an access_token and refresh_token for subsequent operations.

Token refresh

This method is used to refresh an expired access_token using a refresh_token. If the access_token has expired, the application can use the refresh_token to request a new set of tokens.

Info

This method allows an application to obtain user information using a valid access_token. The response includes data that can be used for the application's user interface or other purposes.

Profile

This method retrieves personal and other analytical data about the client (user). Before making this request, the application must request the read.profile grant during the authentication link generation step. If the user consents and the grant is active, the profile data request is queued for processing.

Request

This method retrieves the status of a client profile request.

How It Works#

API Integration Steps#

Partner Service Registration with Freedom ID#

Example Email#

User Data Access Codes#

User Data Parameters#

Link#

Token#

Token refresh#

Info#

Profile#

Request#