# Management and APIs From [Descope Fundamentals](https://learn.descope.io/c/foundations) — Learn the platform by configuring your own project — every module ends in work the app checks for real. Take this course interactively at https://learn.descope.io/c/foundations/management-and-apis --- ![Access Keys and M2M. 2 minutes.](video:management-and-apis-access-keys-and-m2m) ## What you set at creation - Name (required) and an optional description - Expiration — preset durations from 30 days to 2 years, or Never - Permitted IPs — the same CIDR restriction available on management keys - Authorization — tenants and/or roles associated with the key, working exactly as they do for a human user For services that speak standard OAuth, Descope supports the client credentials grant: combine Client ID and access key as :, Base64-encode it, and send it as an Authorization: Basic header with grant_type=client_credentials. That is the recommended path when fronting the exchange with a Federated Application rather than calling exchangeAccessKey directly — useful for gateways expecting a standard OAuth token endpoint. > [!WARNING] > Rotating a key regenerates its secret while preserving ID, name, roles, tenants, expiry, and metadata. The new secret is returned once and the old one stops working immediately, so rotation is a coordinated deploy, not a background task. Keys set to Never expire stay active indefinitely — disciplined manual rotation is the only safeguard against a forgotten long-lived credential. ## Key terms - Access key — a credential a machine presents in exchange for a JWT. - Client credentials grant — the standard OAuth flow exchanging a Base64-encoded Client ID:Access Key pair for a token. - Key rotation — regenerating the secret while preserving everything else; the old secret stops working immediately. ![The Access Key Management page of the API reference. Ten endpoints cover the lifecycle — load, search, create, update, activate, deactivate, and delete, the last three with batch variants — and the two worked examples are creating a key and exchanging it for a JWT, and searching for a key in order to deactivate it.](management-and-apis-access-keys-and-m2m) ## Summary - Why only short-lived JWTs should travel between services - How an access key is scoped, and that it carries tenants and roles like a user - Why rotation is a coordinated deploy rather than a background job - What Never-expiring keys cost you in operational discipline --- ![Management API Overview. 3 minutes.](video:management-and-apis-management-api-overview) ## Three scopes for key roles - Company-level — spans every project: company-full-access, company-asset-mgmt-read / -read-write, company-audit, company-authentication, company-fga-read / -read-write, company-mgmt-keys-read-write. - Project-level — scoped to one project, or with the tag- prefix to every project sharing a tag. Mirrors the company roles: project-full-access, project-asset-mgmt-read-write, project-authentication, and so on. - Descoper-level SCIM — a narrower scope used only for SCIM-driven management of Descoper console accounts, distinct from your application's end users. Keys are not all-or-nothing, and that is worth exploiting: a key scoped to exactly one job does far less damage if it leaks. You can also restrict one to a list of Permitted IPs or CIDR ranges, and it simply will not authenticate from anywhere else regardless of whether the credential escapes. > [!WARNING] > Management keys share the access-key lifecycle: active, deactivated (revoked but recoverable), or deleted (irreversible). Descope's guidance is to rotate at least every 90 days, store them in a secrets manager rather than env files in source control, and generate a separate key per automation purpose rather than reusing one everywhere. The API is organized by resource, and once you have learned the shape of one you have effectively learned them all: every resource supports the same load, search, create, update, and delete pattern, with batch variants where bulk operations are common. That repetition is deliberate — you can usually guess an endpoint before going to look for it. The resources you will reach for most are Users, Tenants, Access Keys, Permissions and Roles, and Applications and Projects. ## Key terms - Management API — the API your backend uses to administer Descope rather than validate end-user sessions. - Management key — the bearer credential every call authenticates with; represents administrative right, not an end user. - Permitted IPs — an optional IP or CIDR allowlist a key is restricted to, regardless of credential leakage. ## Summary - How a Management API call authenticates, and how that differs from a session - The three scopes a key's roles can sit at - The rotation, storage, and scoping practices that limit blast radius - That every resource follows one predictable CRUD-plus-batch shape --- ![Tenant Management via API/SDK. 2 minutes.](video:management-and-apis-tenant-management-via-api) ## What you can set at creation or later - Self-provisioning domains — email domains that automatically route a signing-up user into this tenant, so alice@acme.com lands in the Acme tenant with no manual assignment. - Custom attributes — tenant-level data like a paid tier or region, definable as text, numeric, boolean, single-select, multi-select, or date, managed from the Tenants page's Custom Attributes tab. Roles live at the project level, available across every tenant, or at the tenant level, specific to one tenant's authorization model. The same user can hold different roles in different tenants at once — an Admin in Acme and a Member in Globex — without needing a second identity, because identity is project-scoped while authorization is tenant-scoped. A project-level role can be set as a tenant's default via updateDefaultRoles, so every new user created for that tenant is assigned it automatically. That is a common onboarding shortcut for B2B apps that want every new member of a customer org to start with baseline access. The pre-configured Tenant Admin role is worth knowing by name: it bundles SSO Admin, User Admin, and Impersonate, letting its holder manage that tenant's SSO configuration and users, and impersonate them for support. ## Key terms - Self-provisioning domain — an email domain automatically routing a signing-up user into a specific tenant. - Default role — a project-level role automatically assigned to every new user of a tenant, set via updateDefaultRoles. - Tenant Admin — a pre-configured role bundling SSO Admin, User Admin, and Impersonate for a given tenant. ![The Tenant Management API reference. Six endpoints — load all, load by ID, search, create, update, delete — against the twenty-five or so on the user side, which is the proportion worth taking away. The worked examples are creating a tenant and then adding users to it, and updating a tenant's `selfProvisioningDomains`.](management-and-apis-tenant-management-via-api) ## Summary - That a name is all a tenant needs, and when to supply your own ID - How one identity holds different roles in different tenants - What self-provisioning domains automate - What the Tenant Admin role actually grants --- ![User Management via API/SDK. 2 minutes.](video:management-and-apis-user-management-via-api) Most user records get created by users themselves, walking through a flow. The ones that do not are the interesting cases: a customer imported from a legacy system, an account provisioned by an onboarding pipeline, a support engineer correcting an email address, a test user your CI suite signs in as. A user needs only a login ID to exist. Everything else — email, phone, display name, roles, tenant memberships, custom attributes — is optional at creation and can be layered on afterwards. ## The core operations - Create User — creates one user, optionally sending an invite by email or SMS that flips their status from invited to active once they complete any supported sign-in method. - Search Users — the primary way to look users up by criteria rather than by ID: login ID, status, tenant, role, and more. - Update User — a full overwrite of the record. Field-specific variants exist for email, phone, login ID, display name, picture, and custom attributes when you want a targeted change. - Delete User / Batch Delete Users — irreversible removal, singly or in bulk. Batch Create Users accepts an array in a single request and returns two lists — createdUsers and failedUsers — so one malformed record in a batch of a hundred does not block the other ninety-nine. It supports the same fields as single creation, including tenants and roles per tenant, custom attributes, and multiple login IDs per user via additionalIdentifiers. > [!NOTE] > Test users are a first-class concept, not a naming convention. Creating a user with the test flag set to true unlocks a set of endpoints that drive authentication flows end-to-end without touching a real inbox or phone — which is what makes automated end-to-end auth testing practical. ## Key terms - Create User — creates a single user from just a login ID. - Batch Create Users — accepts an array and returns separate createdUsers and failedUsers lists. - Test user — created with the test flag, unlocking endpoints to drive auth flows without a real inbox or phone. - additionalIdentifiers — lets a single user hold multiple login IDs. ![The User Management API reference. The overview gives the bearer format every call uses, `:`, with keys generated from Company → Management Keys. Below it the endpoint list runs past twenty-five entries: load, search and create alongside a long tail of single-field updates — email, phone, login ID, display name, picture, custom attributes, roles and tenants — which is the shape worth noticing rather than any one entry.](management-and-apis-user-management-via-api) ## Summary - That a login ID is the only required field - That Update User overwrites, and which variants change one field instead - That deletion is irreversible, singly or in batch - Why a partial batch failure does not cost you the whole batch ---