openapi: 3.0.3
info:
title: Descope Apps Mgmt API
description: Descope API
contact:
name: Descope
url: https://descope.com
email: support@descope.com
version: 0.0.1
servers:
- url: https://api.descope.com
description: Descope Production
- url: '{customUrl}'
description: Custom server URL
variables:
customUrl:
default: https://api.descope.com
description: Your Descope API base URL
security:
- Descope Project ID: []
Descope Project ID:Refresh JWT: []
Descope Project ID:Session JWT: []
Descope Project ID and Management Key: []
Descope Project ID:Access Key: []
tags:
- name: Mgmt
paths:
/v1/mgmt/inboundapp/app/{projectId}/register:
post:
tags:
- Mgmt
description: Register Third Party Application according to RFC 7591
operationId: RegisterThirdPartyApplication
parameters:
- name: projectId
in: path
description: Auto fill by proto from the requested URL
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/managementv1.RegisterThirdPartyApplicationRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/managementv1.RegisterThirdPartyApplicationResponse'
x-publishYaml: thirdPartyApps
security: []
x-meta:
title: undefined | Third Party Apps
description: Register Third Party Application according to RFC 7591
keywords: api, third party apps
/v1/mgmt/mcp/client/{projectId}/{mcpServerId}/register:
post:
tags:
- Mgmt
description: Register MCP Server client according to RFC 7591
operationId: RegisterMcpServerClient
parameters:
- name: projectId
in: path
description: Auto fill by proto from the requested URL
required: true
schema:
type: string
- name: mcpServerId
in: path
description: Auto fill by proto from the requested URL (only in agentic hub)
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/managementv1.RegisterThirdPartyApplicationRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/managementv1.RegisterThirdPartyApplicationResponse'
x-publishYaml: thirdPartyApps
security: []
x-meta:
title: undefined | Third Party Apps
description: Register MCP Server client according to RFC 7591
keywords: api, third party apps
/v1/mgmt/accesskey:
get:
tags:
- Mgmt
summary: Load An Access Key
description: '### Load an access key, using a valid management key.
This API endpoint allows administrators to load the details of an existing access key.
The response contains details of the access key including associated roles and tenants as well as details of the key''s creation, status, and expiration.
### Next Steps
Once you have this data, you can utilize the response to [Update an access key](/api/management/access-keys/update-access-key), [Activate an access key](/api/management/access-keys/activate-access-key), [Deactivate an access key](/api/management/access-keys/deactivate-access-key), or [Delete an access key](/api/management/access-keys/delete-access-key).
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: LoadAccessKey
parameters:
- name: id
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 1
x-meta:
title: Load An Access Key | Access Key Management
description: Load an access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/import:
post:
tags:
- Mgmt
summary: Import Access Key
description: Import an access key by providing its plaintext value, using a valid management key.
operationId: ImportAccessKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportAccessKeysRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImportAccessKeysResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 2
x-meta:
title: Import Access Key | Access Key Management
description: Import an access key by providing its plaintext value, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/search:
post:
tags:
- Mgmt
summary: Search Access Keys
description: '### Search access keys, using a valid management key.
This API endpoint allows administrators to search for details of existing access keys for a given array of tenants.
The response contains an array of details for the access keys returned by the search including associated roles and tenants as well as details of the key''s creation, status, and expiration.
### Next Steps
Once you have this data, you can utilize the response to [Update an access key](/api/management/access-keys/update-access-key), [Activate an access key](/api/management/access-keys/activate-access-key), [Deactivate an access key](/api/management/access-keys/deactivate-access-key), or [Delete an access key](/api/management/access-keys/delete-access-key).
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: SearchAccessKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAccessKeysRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeysResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 2
x-meta:
title: Search Access Keys | Access Key Management
description: Search access keys, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/create:
post:
tags:
- Mgmt
summary: Create Access Key
description: '### Create an access key, using a valid management key.
This API endpoint allows administrators to create an access key.
During the creation of the access key, you can set the name, expiration time, roles and tenant:role pairs to associated with the key.
### Next Steps
Once you have the access key, you can utilize it to configure external items such as [SCIM](/api/scimmanagement/), or use it to [exchange for a JWT](/api/access-keys/exchange-key).
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: CreateAccessKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccessKeyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccessKeyResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 3
x-meta:
title: Create Access Key | Access Key Management
description: Create an access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/update:
post:
tags:
- Mgmt
summary: Update Access Key
description: '### Update an existing access key, using a valid management key.
This API endpoint allows administrators to update an existing access key. With this endpoint, you can only update the access key''s name.
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: UpdateAccessKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccessKeyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 4
x-meta:
title: Update Access Key | Access Key Management
description: Update an existing access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/activate:
post:
tags:
- Mgmt
summary: Activate Access Key
description: '### Activate an existing access key, using a valid management key.
This API endpoint allows administrators to activate an existing access key.
### Next Steps
Once you have reactivated the access key, you can utilize it to configure external items such as [SCIM](/api/scimmanagement/), or use it to [exchange for a JWT](/api/access-keys/exchange-key).
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: ActivateAccessKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 5
x-meta:
title: Activate Access Key | Access Key Management
description: Activate an existing access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/deactivate:
post:
tags:
- Mgmt
summary: Deactivate Access Key
description: '### Deactivate an existing access key, using a valid management key.
This API endpoint allows administrators to deactivate an existing access key.
Once the access key has been deactivated, it''s access will be revoked until reactivated.
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: DeactivateAccessKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 6
x-meta:
title: Deactivate Access Key | Access Key Management
description: Deactivate an existing access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/activate/batch:
post:
tags:
- Mgmt
summary: Batch Activate Access Keys
description: '### Activate existing access keys in batch, using a valid management key.
This API endpoint allows administrators to activate existing access keys in batch.
### Next Steps
Once you have reactivated the access key, you can utilize it to configure external items such as [SCIM](/api/scimmanagement/), or use it to [exchange for a JWT](/api/access-keys/exchange-key).
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: ActivateAccessKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyBatchRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 7
x-meta:
title: Batch Activate Access Keys | Access Key Management
description: Activate existing access keys in batch, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/deactivate/batch:
post:
tags:
- Mgmt
summary: Batch Deactivate Access Keys
description: '### Deactivate existing access keys in batch, using a valid management key.
This API endpoint allows administrators to deactivate existing access keys in batch.
Once the access keys have been deactivated, their access will be revoked until reactivated.
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: DeactivateAccessKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyBatchRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 8
x-meta:
title: Batch Deactivate Access Keys | Access Key Management
description: Deactivate existing access keys in batch, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/delete/batch:
post:
tags:
- Mgmt
summary: Batch Delete Access Keys
description: '### Delete existing access keys in batch, using a valid management key.
This API endpoint allows administrators to delete existing access keys in batch.
Once the access keys have been deleted, their access will be revoked.
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: DeleteAccessKeys
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyBatchRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 9
x-meta:
title: Batch Delete Access Keys | Access Key Management
description: Delete existing access keys in batch, using a valid management key.
keywords: api, access key management
/v1/mgmt/accesskey/delete:
post:
tags:
- Mgmt
summary: Delete Access Key
description: '### Delete an existing access key, using a valid management key.
This API endpoint allows administrators to delete an existing access key.
Once the access key has been deleted, it''s access will be revoked.
### See also
- See [Access Key Management](/access-keys) for further details on managing access keys.'
operationId: DeleteAccessKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: accessKeyManagement
x-order: 10
x-meta:
title: Delete Access Key | Access Key Management
description: Delete an existing access key, using a valid management key.
keywords: api, access key management
/v1/mgmt/audit/search:
post:
tags:
- Mgmt
summary: Search Audit
description: '### Search the audit log, using a valid management key.
This API endpoint allows you to search the audit log utilizing various search parameters and returns the results in JSON format.'
operationId: SearchAudit
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAuditRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAuditResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: auditManagement
x-order: 1
x-meta:
title: Search Audit | Audit Management
description: Search the audit log, using a valid management key.
keywords: api, audit management
/v1/mgmt/audit/event:
post:
tags:
- Mgmt
summary: Create Audit Event
description: '### Create an audit log event, using a valid management key.
This API endpoint allows you to create an audit log utilizing various parameters and returns the results in JSON format.'
operationId: CreateAuditEvent
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAuditRequest'
required: true
responses:
'200':
description: OK
content: {}
security:
- Descope Project ID and Management Key: []
x-publishYaml: auditManagement
x-order: 2
x-meta:
title: Create Audit Event | Audit Management
description: Create an audit log event, using a valid management key.
keywords: api, audit management
/v1/mgmt/analytics/search:
post:
tags:
- Mgmt
summary: Search Analytics
description: Search analytics (summarized) data grouped by time periods, using a valid management key.
operationId: SearchAnalytics
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAnalyticsRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAnalyticsResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: auditManagement
x-order: 3
x-meta:
title: Search Analytics | Audit Management
description: Search analytics (summarized) data grouped by time periods, using a valid management key.
keywords: api, audit management
/v1/mgmt/user:
get:
tags:
- Mgmt
summary: Load User
description: '### Load a user''s data, using a valid management key.
This API endpoint takes the user''s loginId and then returns details of a user utilizing a valid management key. The response includes the following; however, there are additional items in the response that you can see below by expanding the response 200 OK.
- loginIds
- userId
- name
- email
- phone
- verified settings (phone, email)
- Tenant configurations - which tenantIds, which roleNames
_Note: Suppose you frequently load a user for a specific user detail, such as their email address or a
particular custom attribute. In that case, you can save execution time and additional API/SDK calls to load
the user by adding the items to the custom claim. For details on adding items to the custom claims, see
[this documentation](/security-best-practices/custom-claims#using-custom-claims-within-descope-flows)._
_Note: If you have access to all federated applications, the list will return as an empty array. Descope allows you to restrict which apps each user has access to, but by default gives access to all applications._
### Next Steps
Once you have this data, you can utilize the response to prepare the payload to perform an [Update](/api/management/users/update-user) on the user.
### See also
- See [Manage Users](/manage/users) for further details on managing users.
- See [The User Object](/api/overview#the-user-object) for further details on the user object.'
operationId: LoadUser
parameters:
- name: loginId
in: query
schema:
type: string
- name: userId
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 1
x-meta:
title: Load User | User Management
description: Load a user's data, using a valid management key.
keywords: api, user management
/v1/mgmt/user/create/test:
post:
tags:
- Mgmt
summary: Create Test User
description: Create a test user, using a valid management key.
operationId: CreateTestUser
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 1
x-meta:
title: Create Test User | User Management
description: Create a test user, using a valid management key.
keywords: api, user management
/v1/mgmt/user/provider/token:
get:
tags:
- Mgmt
summary: Get User Provider Token
description: '### Get an existing user''s provider token, using a valid management key.
This API endpoint will loads the user''s access token generated by the OAuth/OIDC provider, using a valid management key. When querying for OAuth providers, this only applies when utilizing your own account with the provider and have selected `Manage tokens from provider` selected under the [social auth methods](https://app.descope.com/settings/authentication/social).
### Query Params
- `loginId` - The loginId of the user you want to get the provider token for.
- `provider` - The provider you want to get the token for.
- `withRefreshToken (optional)` - set to true to also return the refresh token.
- `forceRefresh (optional)` - set to true to force a refresh of the token.
### See also
- See [Manage Users](/manage/users) for further details on managing users.
- See [The User Object](/api/overview#the-user-object) for further details on the user object.
- See [Provider Options](/auth-methods/oauth#social-login-oauth-providers) for a the out of the box list of providers.'
operationId: GetUserProviderToken
parameters:
- name: loginId
in: query
schema:
type: string
- name: provider
in: query
schema:
type: string
- name: withRefreshToken
in: query
schema:
type: boolean
- name: forceRefresh
in: query
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserProviderTokenResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 2
x-meta:
title: Get User Provider Token | User Management
description: Get an existing user's provider token, using a valid management key.
keywords: api, user management
/v1/mgmt/users/load:
post:
tags:
- Mgmt
summary: Load Users
description: Load users by their IDs, using a valid management key.
operationId: LoadUsers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LoadUsersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 2
x-meta:
title: Load Users | User Management
description: Load users by their IDs, using a valid management key.
keywords: api, user management
/v1/mgmt/user/search:
post:
tags:
- Mgmt
summary: Search Users
description: Search users, using a valid management key.
operationId: SearchUsers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchUsersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
deprecated: true
security:
- Descope Project ID and Management Key: []
x-publishYaml: __NO_PUBLISH__
x-order: 3
x-meta:
title: Search Users | User Management
description: Search users, using a valid management key.
keywords: api, user management
/v2/mgmt/user/search/test:
post:
tags:
- Mgmt
summary: Search test Users
description: Search test users, using a valid management key.
operationId: SearchTestUsers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchUsersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 3
x-meta:
title: Search test Users | User Management
description: Search test users, using a valid management key.
keywords: api, user management
/v2/mgmt/user/search:
post:
tags:
- Mgmt
summary: Search Users
description: '### Search for users, using a valid management key.
This API endpoint will search for users utilizing a valid management key. Searches can be defined with any combination of roles or tenants. You can also only send the request with an empty payload to return all users.
The response will include the following details on all users within an array of objects:
- loginIds
- userId
- name
- email
- phone
- verified settings (phone, email)
- Tenant configurations (tenantIds, roleNames)
### Next Steps
You can then parse through the response in order to find any users which you may need to delete, update, etc.
### See also
- See [Manage Users](/manage/users) for further details on managing users.
- See [The User Object](/api/overview#the-user-object) for further details on the user object.'
operationId: SearchUsers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchUsersRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 4
x-meta:
title: Search Users | User Management
description: Search for users, using a valid management key.
keywords: api, user management
/v1/mgmt/user/history:
post:
tags:
- Mgmt
summary: Get User's Login History
description: '### Get an user''s login history, using a valid management key.
This API endpoint will loads the user''s login history based on the user''s userId.
### See also
- See [Manage Users](/manage/users) for further details on managing users.
- See [The User Object](/api/overview#the-user-object) for further details on the user object.'
operationId: UsersAuthHistory
requestBody:
content:
application/json:
schema:
type: object
properties: {}
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UsersAuthHistoryResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 5
x-meta:
title: Get User's Login History | User Management
description: Get an user's login history, using a valid management key.
keywords: api, user management
/v1/mgmt/user/patch/batch:
patch:
tags:
- Mgmt
summary: Patch Users Batch
description: Patch users in batch, using a valid management key.
operationId: PatchUserBatch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchUserBatchRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PatchUserBatchResponse'
security:
- Descope Project ID and Management Key: []
x-publishYaml: userManagement
x-order: 5.1
x-meta:
title: Patch Users Batch | User Management
description: Patch users in batch, using a valid management key.
keywords: api, user management
/v1/mgmt/user/create:
post:
tags:
- Mgmt
summary: Create User
description: "### Create a new user, using a valid management key.\n\nThis API endpoint will create a new user utilizing a valid management key.\n\nThis API endpoint allows you to configure all aspects of a user:\n- loginId\n- email\n- phone\n- verified settings (phone, email) - one must be set to true\n- displayName\n- roleNames\n- Tenant configurations - which tenantIds, which roleNames. The userTenants can include multiple items\nEx:\n```\n\"userTenants\": [\n{\n \"tenantId\": \"T2IMjmRfYTQHlbaastz3im59ERS3\",\n \"roleNames\": [\n \"Test\"\n ]\n},\n{\n \"tenantId\": \"T2Igau6dX1R6SkomtFCdBLrc3r67\",\n \"roleNames\": [\n \"Test\"\n ]\n}\n```\n\nAdditionally, you can create a user with multiple login IDs by passing an array of loginIds in string format within the `additionalIdentifiers` key.\n\n### Next Steps\n\nOnce the user is created, the user can then login utilizing any sign-in api supported. This will then switch the user from invited to active.\n\n### See also\n\n- See [Manage User](/manage/users) for further details on managing users.\n- See [The User Object](/api/overview#the-user-object) for further details on the user object."
operationId: CreateUser
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserReques
# --- truncated at 32 KB (469 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descope/refs/heads/main/openapi/descope-mgmt-api-openapi.yml