# Authentication

Session authentication is designed as a short-lived JWT tokens, requiring periodic refresh of access token throughout a session which lasts one hour. This approach minimizes the transmission of the secret (API key) over the network, reducing the risk of unauthorized access.

Example API request using access_token:




 

GET /v3/individuals

Content-Type: application/json
Authorization: Bearer <access_token>

# Session and token timeframes

Expiration Timeframes:

  • Access Token: 15 minutes
  • Session: 60 minutes

When the access token expires, a request will result in a 401 Unauthorized response, indicating the requirement for refreshing the token using the POST /auth/refresh endpoint.

Example login to session request:

 



 



POST /v3/auth/login
Content-Type: application/json

{
  "api_key": "c5f90f4b-9d69-416a-8611-8a8c8d605c36"
}

Response:




 
 



HTTP 200 OK

{
  "access_token": "eyJraWQiOiIxIiwiYWxnIjoi...",
  "refresh_token": "eyJzZXNzaW9uSWQiOiJmMjUa..."
}

Successful login request returns access_token and refresh_token.

The generated refresh token is valid during the entire session, but attempting to refresh before access token expiration will result in a 400 Bad Request response. Keep the latest refresh token for subsequent access refresh.

As example, the session can be divided into four 15-minute timeframes within one hour, initiated by the POST /auth/login request followed by three consecutive POST /auth/refresh requests.

Intergiro 3d authentication

Example refresh access token request:

 



 


POST /v3/auth/refresh
Content-Type: application/json

{
  "refresh_token": "c5f90f4b-9d69-416a-8611-8a8c8d605c36"
}

Response:




 
 


HTTP 200 OK

{
  "access_token": "eyJraWQiOiIxIiwiYWxnIjoi...",
  "refresh_token": "eyJzZXNzaW9uSWQiOiJmMjUa..."
}

# Tokens storage

Store access or refresh tokens securely, considering the runtime environment:

  • For traditional backend applications, store as a local variable.
  • Other options include Redis or other databases.

WARNING

Do not store tokens in end-user device local storage or cookies. The Intergiro 3d API is server-to-server and should never be used from the end user device or frontend application. Sensitive data, such as access and refresh tokens, should be stored securely on the backend. Modern runtime environments may complicate local state preservation; in such cases, consider using a central storage like Redis or a database.

# Session misuse

Dropping a valid session prematurely and creating new sessions (when access tokens are not refreshed properly) can trigger our DDoS and Fraud monitoring mechanisms, leading to service disruption impacting end users. We strongly recommend reusing the session until its intended end to avoid any issues.