Access Keys with SDKs

If you wish to learn more about Access Keys in general, visit our section on Access Key Management.

You can use Descope Management SDK for common access key management operations like create access key, update custom claims, delete access key, etc.

Install SDK

The Management SDK requires a management key, which can be generated here.

Terminal

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

This operation is used to create an access key. At the time of creation of the access key, you can provide the name, expiration duration, tenants, and roles associated with the key. After the successful creation of the key, the response object contains id of the key and key value. The key value is only delivered at the creation time from Descope service, and your application must store or deliver to the connecting machine based on your use case. Your application can use the key id for updating the name, deleting, etc. An access key must have a name and expiration, other fields are optional. Roles should be set directly if no tenants exist, otherwise set on a per-tenant basis.

// Args:
//   name (str): Access key name.
const name = "xxxx"
//   expireTime (int): Access key expiration. Leave at 0 to make it indefinite.
const expireTime = 0
//   roles (List[str]): An optional list of the access key's roles without tenant association. These roles are mutually exclusive with the `key_tenant` roles, which take precedence over them.
const roles = ["TestRole1"]
// userId (str): An optional user id to associate to a role. If the user is disabled or deleted - it will affect the access key accordingly.
const userId = 'yyyy'
//   keyTenants (List[AssociatedTenant[]]): An optional list of the access key's tenants, and optionally, their roles per tenant. These roles are mutually exclusive with the general `role_names`, and take precedence over them.
const keyTenants = [{tenantId: 'TestTenant'}]
// CustomClaims Record<string, any>: An optional record of custom attributes to add on the top level of the jwt for the access key.
const customClaims = {'key':'value'}
 
// Create with associated roles rather than tenants
// const resp = await descopeClient.management.accessKey.create(name, expireTime, roles, userId, null, customClaims)
 
// Create with associated tenants rather than roles
const resp = await descopeClient.management.accessKey.create(name, expireTime, userId, null, keyTenants, customClaims)
if (!resp.ok) {
  console.log("Failed to create access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully created access key.")
  console.log(resp.data)
}

Load Access Key

The Descope SDK allows administrators to use a management key to load details of an existing access key.

// Args:
//   id (str): The id of the access key to be loaded.
const id = "xxxx"
 
const resp = await descopeClient.management.accessKey.load(id);
if (!resp.ok) {
  console.log("Failed to load access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded access key.")
  console.log(resp.data)
}

Search Access Keys

The Descope SDK allows administrators to use a management key to search for existing access keys. Administrators can search all or search based on a specific tenantIds.

// Args:
//   tenantIds (List[str]): Optional list of tenant IDs to filter by
const tenantIds = ["TestTenant"]
 
// Search all access keys:
// const resp = await descopeClient.management.accessKey.searchAll(null)
 
// Search keys based on tenantIds
const resp = await descopeClient.management.accessKey.searchAll(tenantIds)
if (!resp.ok) {
  console.log("Failed to search access keys.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully searched access keys.")
  console.log(resp.data)
}

Update Access Key

The Descope SDK allows administrators to use a management key to update the name of an existing access key. It is important to note that all parameters are used as overrides to the existing access key; empty fields will override populated fields.

// Args:
//   id (str): The id of the access key to update.
const id = "xxxx"
//   name (str): The updated access key name.
const name = "xxxx"
 
const resp = await descopeClient.management.accessKey.update(id, name);
if (!resp.ok) {
  console.log("Failed to update access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated access key.")
  console.log(resp.data)
}

Activate Access Key

The Descope SDK allows administrators to use a management key to activate an existing access key that is currently deactivated.

// Args:
//   id (str): The id of the access key to be activated.
const id = "xxxx"
 
const resp = await descopeClient.management.accessKey.activate(id);
if (!resp.ok) {
  console.log("Failed to activate access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully activated access key.")
  console.log(resp.data)
}

Deactivate Access Key

The Descope SDK allows administrators to use a management key to deactivate an existing access key. After deactivating an access key, it will no longer be usable. The key will persist within the project, and can be activated again if needed.

// Args:
//   id (str): The id of the access key to be deactivated.
const id = "xxxx"
 
const resp = await descopeClient.management.accessKey.deactivate(id);
if (!resp.ok) {
  console.log("Failed to deactivate access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully deactivated access key.")
  console.log(resp.data)
}

Delete Access Key

The Descope SDK allows administrators to use a management key to delete an existing access key. Once an access key is deleted, it is removed from the project and no longer usable. This action is irreversible.

// Args:
//   id (str): The id of the access key to be deleted.
const id = "xxxx"
 
const resp = await descopeClient.management.accessKey.delete(id);
if (!resp.ok) {
  console.log("Failed to delete access key.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully deleted access key.")
  console.log(resp.data)
}

Exchange Access Keys

The Descope SDK allows for exchanging access keys for a JWT token. 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. You can also provide this method with a custom claims object, that will eventually nest the custom claims inside the nsec key. The custom claims that sit under nsec are in a less secure state by definition in contrast to custom claims that are created with the access key itself.

// Args:
//   accessKey (str): The access key
const accessKey = "xxxx"
// loginOptions: Optional advanced controls over login parameters, e.g. custom claims:
const loginOptions = {customClaims: {"key":"value"}}
 
try {
    const authInfo = await descopeClient.exchangeAccessKey(mykey, loginOptions);
    console.log(`Exchanged access key for JWT: ${authInfo.jwt}`);
} catch (err) {
    console.log(`Failed to exchange access key: ${err}`);
}

Was this helpful?