# 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.
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.