Access Keys
If you want to view the SDK documentation for Access Key Management, click here.
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. By 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. The connecting machine can then use this JWT token to make API calls to your application. Your application backend can validate the session token as covered in the session management article.
Each access key has an expiration duration and can be associated with tenants and roles. The tenants and roles association work similarly to the user management. The expiration duration is used to calculate the key's expiry time, and the exchanged session token will be valid until the expiry time. The access keys can be created or deleted using the Descope console interface or the management SDK.
You can also configure the Access Key Session Token Timeout within project settings.
This timeout controls how long the session token is valid after exchanging the access key for a session token.
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. Deleting access keys will remove the access key's details from the Descope project.
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.
Also note that, when exchanging access keys for a JWT, you can set custom claims, including the user ID, on the JWT token.
Adding Permitted IPs to Access Keys
At the time of creating access keys, Descope now supports an attribute for CIDR restrictions. This is achieved by adding in permitted IPs associated with that specific access key. This enables network allow lists per access key, so an access key can only work if it's being used from a specific set of whitelisted IP addresses. Descoper can set one or more CIDRs for an access key. This field is not editable once the access key has been created.
