Token

Exchange JWT

Exchanges a user’s JWT for a new, short-lived token using the application’s access key. The new token has its audience (aud) set to the application’s ID and its expiration (exp) set to 10 minutes from the request time, while the original iat (“issued at”) claim remains unchanged. A new rat (“reissued at”) claim is added to record the reissue timestamp in Unix time. All other claims from the original token are preserved.

JWT Claim Updates:

  • aud: set to the application ID

  • exp: set to 10 minutes from the request time

  • rat: set to the request timestamp (Unix time)

Access Requirements

A valid application access key must be provided in the Authorization: Bearer header.

Note

Token expiration is automatically set to 10 minutes from the request time.

Request

POST /api/permissions/exchangeJwt

  • Authorization string required

    Bearer token representing the application’s access key. Must be provided in the header as Bearer <accessKey>.

  • jwt string required

    JWT token to be exchanged. Must be valid.

Request example
POST /api/permissions/exchangeJwt
Header
Authorization: Bearer 2f6a9b8...
Content-Type: application/json
Body
{
  "jwt": "eyJhbGciOiJI..."
}

Response

Success: 200 OK

  • status string required

    Indicates the response status.

    • “OK”

  • jwt string required

    The new user’s JWT.

Response example
{
  "status": "OK",
  "jwt": "<new JWT token>"
}

Forbidden: 403 Forbidden

  • status string required

    Indicates the response status.

    • “ERROR”

  • error string required

    The error message describing the reason for the failure. Returned only when status is "ERROR".

    • “Wrong access key”

    • “Wrong JWT: <detailed error message>”

Response example
{
  "status": "ERROR",
  "error":  "Wrong access key"
}

Internal Error: 500 Internal Server Error

  • status string required

    Indicates the response status.

    • “ERROR”

  • error string required

    The error message describing the reason for the failure. Returned only when status is "ERROR".

    • “Cannot create new JWT”

Response example
{
  "status": "ERROR",
  "error":  "Cannot create new JWT"
}

Refresh JWT

Refreshes the expiration time and selected user claims for a given JWT. The method validates the request using a combination of the JWT (provided in the header or body) and a digital signature (Request-Sign header). If the request is valid, it generates a new JWT with refreshed expiration (exp) and updated user information: nickname (nick), tags (tgs), and “reissued at” (rat) fields.

Access Requirements

The request must include a valid JWT in the Authorization: Bearer header and a valid Request-Sign signature.

Note

If the provided token has expired but the request is otherwise valid, it still allows refreshing the token.

Request

POST /api/permissions/refreshJwt

  • Authorization string required

    Bearer token containing the JWT to validate. Must be provided in the header as Bearer <jwt>.

  • Request-Sign string required

    Request signature used to verify the integrity of the request body.

Request example
POST /api/permissions/refreshJwt
Header
Authorization: Bearer 2f6a9b8...
Request-Sign: 89fbc28e7....
Body
{
  "jwt": "eyJhbGc...."
}

Response

Success: 200 OK

  • status string required

    Indicates the response status.

    • “OK”

  • jwt string required

    The new refreshed user’s JWT.

Response example
{
  "status": "OK",
  "jwt": "<new refreshed JWT token>"
}

Bad Request: 400 Bad Request

  • status string required

    Indicates the response status.

    • “ERROR”

  • error string required

    The error message describing the reason for the failure. Returned only when status is "ERROR".

    • “Wrong request: <detailed information>”

    • “Wrong request format”

Response example
{
  "status": "ERROR",
  "error":  "Wrong request format"
}

Forbidden: 403 Forbidden

  • status string required

    Indicates the response status.

    • “ERROR”

  • error string required

    The error message describing the reason for the failure. Returned only when status is "ERROR".

    • “Invalid JWT: <detailed information>”

    • “Wrong token source”

Response example
{
  "status": "ERROR",
  "error":  "Wrong token source"
}

Internal Error: 500 Internal Server Error

  • status string required

    Indicates the response status.

    • “ERROR”

  • error string required

    The error message describing the reason for the failure. Returned only when status is "ERROR".

    • “Cannot retrieve user info”

    • “Cannot create new JWT”

Response example
{
  "status": "ERROR",
  "error":  "Cannot create new JWT"
}