Management Keys with SDKs

You can use the Descope management SDK to create, update, delete, load, or search Management Keys. The management SDK requires a management key, which can be generated here.

If you wish to learn more about how Management Keys work, see Company Settings.

Management Keys using the management SDK

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

Search All Management Keys

Note

You can also use our Search Management Keys API to list all Management Keys.

This operation returns all Management Keys in your company.

const resp = await descopeClient.management.managementKey.search();
if (!resp.ok) {
  console.log("Failed to search management 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 management keys.")
  console.log(resp.data)
}

Load Management Key by ID

Note

You can also use our Get Management Key API to load a specific Management Key.

This operation loads an existing Management Key by ID, including its name, description, status, expiration, permitted IPs, and role configuration. The key secret (cleartext) is not returned.

// Args:
//    id (str): The Management Key ID.
const id = "key-id";

const resp = await descopeClient.management.managementKey.load(id);
if (!resp.ok) {
  console.log("Failed to load management 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 management key.")
  console.log(resp.data)
}

Create Management Key

Note

You can also use our Create Management Key API to create a Management Key.

This operation creates a new Management Key. A name and role configuration (reBac) are required; description, expiration (expiresIn in seconds; 0 for no expiration), and permitted IPs are optional. Roles can be set at the company, project, or tag level and cannot be changed after creation. The response includes the key details and the cleartext secret — store the secret securely, as it is only returned once.

// Args:
//    name (str): Required name for the management key.
const name = "my-key-name";
//    reBac (MgmtKeyReBac): Role-based access control configuration for the key.
const reBac = { companyRoles: ["company-fga-read-write"] };
//    description (str): Optional description.
const description = "Optional description";
//    expiresIn (number): Optional expiration time in seconds (0 for no expiration).
const expiresIn = 3600;
//    permittedIps (List[str]): Optional list of IP addresses or CIDR ranges that are allowed to use this key.
const permittedIps = ["10.0.0.1/24"];

const resp = await descopeClient.management.managementKey.create(
  name,
  description,
  expiresIn,
  permittedIps,
  reBac,
);
if (!resp.ok) {
  console.log("Failed to create management 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 management key.")
  console.log(resp.data.key)
  console.log("Key secret (save this!): " + resp.data.cleartext)
}

Update Management Key

Note

You can also use our Update Management Key API to update a Management Key.

This operation updates an existing Management Key's name, description, status (active or inactive), and permitted IPs. All provided fields override the current values, and fields will be reset if not provided. Role and project associations cannot be changed after creation — deactivate or delete the key and create a new one if those need to change.

// Args:
//    id (str): The Management Key ID.
const id = "key-id";
//    name (str): The updated name for the management key.
const name = "updated-key-name";
//    description (str): The updated description for the management key.
const description = "Updated description";
//    status (MgmtKeyStatus): The status of the management key ('active' or 'inactive').
const status = "active";
//    permittedIps (List[str]): Optional list of IP addresses or CIDR ranges that are allowed to use this key.
const permittedIps = ["1.2.3.4"];

const resp = await descopeClient.management.managementKey.update(
  id,
  name,
  description,
  status,
  permittedIps,
);
if (!resp.ok) {
  console.log("Failed to update management 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 management key.")
  console.log(resp.data)
}

Delete Management Key(s)

Note

You can also use our Delete Management Keys API to delete a Management Key.

This operation deletes one or more existing Management Keys by ID. This action is irreversible — deleted keys are removed and can no longer be used or reactivated.

// Args:
//    ids (List[str]): The IDs of the Management Keys to delete.
const ids = ["key-id-1", "key-id-2"];

const resp = await descopeClient.management.managementKey.delete(ids);
if (!resp.ok) {
  console.log("Failed to delete management 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 deleted management keys.")
}

Was this helpful?

On this page