Obtaining JWT tokens for authentication

Instead of an API key, you can use the Textual API to obtain a JSON Web Token (JWT) to use for authentication.

Configuring the JWT and refresh token lifetimes

JWT lifetime

By default, a JWT is valid for 30 minutes.

On a self-hosted instance, to configure a different lifetime, set the environment variable SOLAR_JWT_EXPIRATION_IN_MINUTES.

Refresh token lifetime

You use a refresh token to obtain a new JWT. By default, a refresh token is valid for 10,000 minutes, which is roughly equivalent to 7 days.

On a self-hosted instance, to configure a different lifetime, set the environment variable SOLAR_REFRESH_TOKEN_EXPIRATION_IN_MINUTES.

Obtaining your first JWT and refresh token

To obtain your first JWT and refresh token, you make a login request to the Textual API. Before you can make this call, you must have a Textual account.

To make the call, perform a POST operation against:

<Textual_URL>/api/auth/login

The request payload is:

{"userName": "<Textual username>",
"password": "<Textual password>"}

For example:

{"userName": "[e-mail]",
"password": "MyPassword123!"}

In the response:

• The jwt property contains the JWT.
• The refreshToken property contains the refresh token.

Obtaining a new JWT and refresh token

You use the refresh token to obtain both a new JWT and a new refresh token.

To obtain the new JWT and token, perform a POST operation against:

<TEXTUAL_URL>/api/auth/token_refresh

The request payload is:

{"refreshToken": "<refresh token>"}

In the response:

• The jwt property contains the new JWT.
• The refreshToken property contains the new refresh token.