Access Keys

Access keys enable machine-to-machine authentication for your application. The access keys in Descope behave similarly to users. When users sign in to your application using your application front-end, a JWT token is delivered to the browser. In contrast, for machine-to-machine communication, the machine connecting to your application presents an access key, and a JWT token is returned to the connecting machine. Your application backend can validate the session token as covered in the session management article, and handle access to resources accordingly.

Here's a diagram illustrating how this authentication works:

Creating an Access Key

Head over to the Access Keys Tab in the Descope Console, and click on the + Access Key button in the top right corner to create a new access key.

You can define the following fields:

• Name (Mandatory): The name for your access key
• Description: The description for your access key
• Expiration: Used to calculate the key's expiry time. When you exchange the access key for a JWT, the JWT will be valid until the expiry time.
• Permitted IPs: If permitted IPs are defined, the access key will only work if it's being used from this list of addresses.
• Authorization: Tenants and/or Roles associated with the Access Key. The Tenants and Roles associations work like how they do for users.

You can also create access keys using our Management SDK function.

Access Key Lifecycle

Access keys will continue to function as long as they are active and not expired. Once the access key is expired or deactivated, it will no longer be usable. Within the UI, you can deactivate (revoke) access keys; however, the access key will remain in the Descope project and may be reactivated if you choose to reactivate them. You can also delete access keys. Once an access key is deleted, it will no longer be usable.

Associating Access Key to Users

Access keys can be created or deleted within the Descope console. While generating the key, you need to provide the name, expiration, tenants, and roles associated with it. You can also set the user of the access key with the management SDK or via the user access key management widget. The rest of the options to edit, delete, or deactivate are provided within the UI.

Exchanging Access Keys for JWTs

If you are using Node, Python, Go, or Java SDKs, you can use the Exchange Access Key function to exchange an access key for a JWT token. This JWT token is what will be used with the rest of your application, to valid that you are authenticated.

If you are not using any of the SDKs, you can also exchange your access key for a JWT using our Exchange Key API endpoint.

Also note that, when exchanging access keys for a JWT, you can set custom claims, including the user ID, on the JWT token.