Converse AI

User authentication

Authenticating a user with the API

To authenticate with the Converse AI API you require the the use of a user token being passed as a custom HTTP request header

X-CONVERSE-TOKEN: {{TOKEN_UUID}}

Create your own token

You can create your own user token using the open API call verify user and adding the additional URL parameter createToken

POST {{your_converse_url}}/api/user/verify?createToken=true

The POST body for this call includes the user email, plaintext password, a value to express how long the token should remain valid, and a boolean flag to state if the token should automatically renew when used.

{
  "email":"admin@example.com",
  "password":"password1",
  "timeout":600,
  "autoRenew":false
}

This works as the user verify call normally works, where it will confirm that the specified email and password are valid, failing if they are not. With the additional createToken URL parameter, after the email and password are validated, it will create a temporary token and return the token value to be used with the custom authentication header. The timeout value is the time in seconds until the token will expire, autoRenew determines if the tokens expiry time should be updated each time it is used, by the amount of time determined by timeout.

Using autoRenew true it is possible to create a token which will not expire as long as it is being used occasionally. Alternatively it is possible to make a token that will never expire regardless if you use it or not by passing -1 as the timeout value. If you do create a token which does not automatically expire you can manually delete them with another API call which will be covered later.

The result of the API call will be a JSON object with a single field with the value that should be passed as the custom authentication header value

{
  "token": "00000000-0000-0000-0000-000000000000"
}

The token is sent as the UUID value shown in the response and does not require any encoding

X-CONVERSE-TOKEN:00000000-0000-0000-0000-000000000000

Verify a user token

The authentication token is verified each time it is used, with the API call returning authenticated if it has expired, but if you want to manually verify a user token it is possible with the verify token API call. This call must be done by an authenticated user, which can include the user token being verified although that would be redundant.

POST {{your_converse_url}}/api/user/token/verify

The POST body should be in the same format as the create token response, a JSON object with a single token field and value

{
  "token":"00000000-0000-0000-0000-000000000000"
}

This API call will return no data but will return a state of 200 OK if the token is valid and 403 Forbidden if the token is invalid.

Delete a user token

All user tokens will be automatically deleted when they are no longer valid with the exception of unlimited tokens. To manually delete a token, unlimited or otherwise, you can use the following API call. This call must be done by an authenticated user, which can include the user token being deleted.

DELETE	{{your_converse_url}}/api/user/token/{{TOKEN_UUID}}

The API call also will not return any data, but will return a state of 200 OK if the token has been deleted successfully.

User authentication

Authenticating a user with the API