Authorization

Last updated on February 19, 2025

GigaChat API is available to legal entities and individual entrepreneurs after concluding an agreement. Payments are made on a postpaid basis.

GigaChat API requests are validated via OAuth 2.0 protocol using access tokens.

The protocol checks if:

• the token session is not expired
• the application has a valid subscription
• the request and the response correspond to the API schema

To use GigaChat API:

1. Get a Client ID and a Client Secret for your application.
2. Add an access token to you service.
3. Use the access token to validate Gigachat API requests.

An access token is valid for 30 minutes after generation. The authentication service sends the expiry time of the token in the exp property:

{
    "tok": "<access_token>",
    "exp": 1695128118
}

Add an Acess Token to API Request Service

Set up your API request service to get access tokens.

Request Template

curl --location --request POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \
--header 'Authorization: Bearer ZTU2MjM2MjctYmI4Yy00MTJjLTk0Yjct232hNjk5OGU4ZWYzOjg4N2QxNWEyLWNiNGYtNDk5OC05NTkxLTViMjZkNjJkMzc1MQ==' \
--header 'RqUID: 6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=GIGACHAT_API_CORP'

Request parameters:

Field	Request
authorization Mandatory	Authorization data. In your GigaChat API project, click Generate new Client Secret and copy the contents of the Authorization data field.
rquid Mandatory	Unigue request ID. The ID is generated according to the (([0-9a-fA-F-])36) pattern. This parameter logs incoming requests and helps you address incidents. To create a unique request ID, use standard libraries and classes for UUID and GUID generation.
scope Mandatory	Version of the API you are getting access to. You can find the value of the scope field in your profile after you create a project. Supported values: GIGACHAT_API_CORP — access to legal entities.

Response Template

{
    "access_token": "eyJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.DCXAAnwXjmRleOrIJcXDWbQwsP5UGSptcY3x5XXRkYZm6x3QkDQBL63DKQZzwrwmtuFbKajq6ULHuQhsmGax-l_R6AhRkr7pWzJi1jpzCenq9PAN2UjF0BX_IiDRgmEExH6_2OtHaJ_7KbudukIOLEgxD9l8WcXFY992dgqLL6eK2nnnUvyfmr4ITc9PWuAFsMIO6jweNFw0e9vRYEDkAbnv9EGR-w9CGwfBsHNWZwZlo7fyu07fkSfmqmGdBvU4344344luNNrHwktSGOzNhpLhu0-0A3KI950vmp_37QY8isDi3epGU3HShdrBZkk70fdXxBKQA.MV2IksoyxTV_c-qm6hSXaQ.LUT4JqOzKqmFOR07-Asq7Fhqj_eYSTXcsJAK-JchmM1QUqhPLBXsUyXXh6ZcjsnN7Q0QXzuBlSjaBWekgWANDirI6HP_MsEM4FxfJAOh73aowC700cEQPPYAxzPYG0d4bOqsZh8Ss57lJB2VM7M6Y2FcG2hb5Q0i2zPskqSWxXejuCyr2uIlY7Fe4bu4NUqtCaKJVwqriVWLfbA0OzZyA0osDc42Ba0u1adFAdaZDCE.IlKOixP8hSUimEI2pdP118Tx0StZjcLdbSauE5R0YAA",
    "expires_at": 1617814516729
}

Response parameters:

Field	Description
access_token Mandatory	A generated access token
expires_at Mandatory	Unix-formatted expiry time of the token in milliseconds

Error Codes

Error Codes	Description
400	Bad request format
401	Unauthorized
500	Internal Server Error

Response Example for Error 400

{
    "code": 1,
    "message": "scope data format invalid"
}

Use the Access Token

Create a request that contains Bearer Access token in the Authorization.

• If the token is valid, the request is sent to GigaChat API.
• If the token is absent or incorrectly formatted, you get an error message about authentication failure.
• If the token is expired, you get an error message about the expiry. In this case, generate a new token.

Check the remaining lifetime of the token before each request. If the current token expires in less than one minute, generate a new token.