API Keys #

Kuzzle allows to create API keys to authenticate users without using an authentication strategy and the auth:login action.

An API key is associated with a standard authentication token that can then be used to authenticate users to the Kuzzle API.

The authentication tokens associated to these API keys may never expire. It is also possible to revoke them at any time by deleting the associated API key.

Create an API Key #

Users can create API keys for their personal use with the auth:createApiKey action.

Administrators can create API keys for other users using the security:createApiKey action.

By default, API keys do not expire. But it is possible to specify the duration of an API key using the argument expiresIn.

It is also possible to set a maximum validity period for an API key under the key security.apiKey.maxTTL in the Kuzzle configuration. This limit will only apply to API key created with the auth controller. Possible values:

• <= -1: disable the use of maxTTL
• >= 0: enable maxTTL with a set value (0 will immediately invalidate an API key when created)

It is also necessary to provide a description of the API key.

Example: Create an API key for the user "ricky", valid for 30 days

Copied to clipboard!

kourou api-key:create ricky --description "Cron API key" --expire "30d"

Kourou returns the authentication token linked to the API key.

API Key properties #

The authentication token is only sent by Kuzzle once. If you lose it, you'll have to delete the API key and recreate a new one.

Property	Description
description	Description
expiresAt	Expiration date in UNIX micro-timestamp format (-1 if the token never expires)
fingerprint	SHA256 hash of the authentication token
token	Authentication token associated with this API key
ttl	Original TTL
userId	User kuid

Search for API Keys #

It is possible to search in its own API keys (auth:searchApiKeys) or in those of all users (security:searchApiKeys).

In order to search an API key of a user, you can use the Kourou api-key:search command.

Example: Search every API keys of the user "ricky"

Copied to clipboard!

kourou api-key:search ricky

The associated authentication token is not returned by Kuzzle.

Delete API Key #

It is possible to use the auth:deleteApiKey and the security:deleteApiKey methods to delete API keys.

Once an API key is deleted, the associated authentication token will be revoked and cannot be used anymore.

Example: Delete the API key with the ID 7ef0022d-a5e2-429b-ab8f-5b6065d345e7 of the user "ricky"

Copied to clipboard!

kourou api-key:delete ricky 7ef0022d-a5e2-429b-ab8f-5b6065d345e7

Check API Key #

It is possible to check the validity of an API Key by running

Example: Check the validity of the API key kapikey-eyJ...2dos

Copied to clipboard!

kourou api-key:check kapikey-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJyaWNreSIsImlhdCI6MTY5NzQ2OTU5NCwiZXhwIjoxNzAwMDYxNTk0fQ.pTuBOPaRoV9VpxuWI6HufxdbSDAbcPK5PNTmHHS2dos