Skip to main content

Authentication

The API uses JWT (JSON Web Token) to authenticate requests. The token is issued against the user's login and password and is passed in every subsequent request.

All API methods are located under /api/ relative to the server address. The server address in the examples is nav.gpspos.ru; your company's address may differ.

Obtaining a token​

POST /api/Token

The only API method that does not require a token.

Request body:

{
  "UserName": "login",
  "Password": "password",
  "SubUserId": 0
}
  • UserName, Password — login and password of a user with API access. An ordinary system account is used: the same credentials apply in the web interface, with the same set of rights.
  • SubUserId — the identifier of a nested account, if sub-users are configured for the user; 0 if sub-users are not used. A token issued for a sub-user limits the returned data to that sub-user's rights.

Response:

{
  "AccessToken": "eyJhbGciOiJIUzI1NiIs...",
  "UserName": "login",
  "ExpiresInSec": 1800
}
  • AccessToken — the access token.
  • UserName — the login of the user the token was issued to.
  • ExpiresInSec — the token lifetime in seconds.

Example request:

curl -X POST https://nav.gpspos.ru/api/Token \
  -H "Content-Type: application/json" \
  -d '{"UserName":"login","Password":"password","SubUserId":0}'

Using the token​

The token is passed in all other requests in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
curl https://nav.gpspos.ru/api/Profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The token grants full access to the user's data within their rights.

Token lifetime​

The token is valid for 30 minutes. The exact value is returned in the ExpiresInSec field and may differ in a particular installation.

A token renewal method is not provided: once the lifetime has elapsed, the token is issued anew with the same POST /api/Token request. A request with an expired token returns 401 Unauthorized. Calls to /Token count towards the rate limit on equal terms with the other methods.

Authentication errors​

Errors are returned in the standard format:

{
  "Status": "FAIL",
  "ErrorMessage": "Invalid username or password."
}
  • 403 Forbidden when obtaining a token — an incorrect login or password, or the account has no API access. API access is enabled by the administrator, see API tools.
  • 401 Unauthorized on a method call — the token is absent, expired, or corrupted.
  • 403 Forbidden on a method call — the token is valid, but the user has no rights to the requested data. The set of rights is defined in the control panel.

The remaining status codes are listed on the Errors and status codes page.