Skip to content

Authorization

Using HTTP header Authorization: Bearer <JWT/ST> to authorize the request.

There are two types of tokens: JWT and ST.

Credential

You will get a Credential after creating an application. The Credential contains the public key and private key.

Example:

{
  "app_id": "<app_id>",
  "id": "<credential_id>",
  "description": "new credential",
  "created_at": 1700239266,
  "expires_at": 1686240000,
  "secret": "<public_key>",
  "secret_private": "<private_key>",
  "type": "JWT-EC-ES256"
}

JWT Token

JWT token is a JSON Web Token, it's a standard for representing claims securely between two parties. It's a signed token, and the server can verify the token's signature to ensure the token's integrity.

How to build JWT token

The JWT Token has three parts: header, payload, and signature. The three parts are separated by a dot.

The header is a JSON object with the following fields:

  • alg: Required, The algorithm used to sign the token, it should be ES256.
  • typ: Required, The type of the token, it's JWT.
  • kid: Required, The key ID of the token.

Example:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "<credential_id>"
}

The payload is a JSON object with the following fields:

  • iss: Required, The issuer of the token, it should be as same as your <app_id>.
  • sub: Required, The subject of the token, it can be as same as your <app_id> or user id.
  • aud: Required, The audience of the token, it should be the server's domain name api.trinity.sosono.ai.
  • exp: Required, The expiration time of the token, it's a Unix timestamp.
  • iat: Required, The issued at time of the token, it's a Unix timestamp.
  • jti: Required, The JWT ID of the token, it's a unique identifier for the token.
  • nbf: Optional, The not before time of the token, it's a Unix timestamp.

Example:

{
  "iss": "<app_id>",
  "sub": "<app_id>",
  "aud": "api.trinity.sosono.ai",
  "exp": 1686240000,
  "iat": 1700239266,
  "jti": "<jwt_id>"
}

Using Credential's private key to make a signature of header and payload with the algorithm ES256 as the JWT token's signature.

Example:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjFOaUlzSW5SNWNDSTZJa3BYVkNJc0kifQ.eyJqdGkiOiJhZWU0MGE5NS1iY2E2LTRjZGYtYWM1NS0xMGVkNjBiYWY1ZGEiLCJpc3MiOiJtVkV0eGQySkxVQzFhZFVnMmNXZEdhVk5MWHoiLCJzdWIiOiJtVkV0eGQySkxVQzFhZFVnMmNXZEdhVk5MWHoiLCJhdWQiOiJhcGkudHJpbml0eS5zb3Nvbm8uYWkiLCJuYmYiOjE3MTY0Nzg0ODksImlhdCI6MTcxNjQ3ODQ4OSwiZXhwIjoxNzI4NjE2MDg5fQ.T6bfW4UYG2m9ldKcccD5M9l7JDOSSrJXKGyXnhjgLRa2vFcsiNrOIhCIzkJSTwvIhQnC0DaY06yYs6CpJkAEaA

For more information about JWT, please refer to RFC 7519.

Or you can use the library to generate the JWT token.

ST Token

ST token is a short-lived token, issued by server, and the client can use it to access the server's resources directly.

It would be like ast-<string>

It's not recommended to use ST token in the client side due to the security issue.