openapi: 3.0.3
info:
title: Descope Apps 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: ''
paths:
/v1/auth/enchantedlink/signup/email:
post:
tags:
- ''
summary: Sign-Up
description: '### Sign-up new end user by sending an enchanted link via email
Initiate a sign-up process by sending an enchanted link to a new end user.
Descope will generate and deliver 3 clickable links to the email address specified,
each is numbered with random 2 digit number. When you initiate the enchanted link, the `linkId` will be returned. This `linkId` needs to be displayed to the user to indicate which link for the user to click
once they receive the email. Only when the correct link is clicked will the user be successfully verified and logged in.
Each clickable link is made up of two parts -
the URI you provide in the `URI` field and the enchanted link token generated by Descope.
For example, if `URI=https://app.mycompany.com/enchantedlink/verify`,
the clickable enchanted link will be `https://app.mycompany.com/enchantedlink/verify?t=enchanted-link-token.`
Enchanted links expire in the time frame configured in the
[Descope console](https://app.descope.com/settings/authentication/enchantedlink),
so sending multiple enchanted links (for example, when an end user tries to sign-up a second or third time)
does not invalidate links that have already been sent.
The return body will include `linkId` and `pendigRef`.
The `linkId` (a 2 digit number) should be presented to the user,
so they will know which link to click in the delivered email.
The endpoint will return a failure code if the email address is already registered.
Note that `URI` is an optional parameter. If omitted - the project setting will apply.
If provided - it should to be part of the allowed `Approved Domains` configured in the project settings.
### Next Steps
1. Verify the enchanted link token using the [Verify Token](/api/enchanted-link/verify-token) endpoint.
2. Poll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint.
### See Also
- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.
- Use the [Sign-In](/api/enchanted-link/sign-in) endpoint to sign-in an existing end user.
- Use the [Sign-In with Auto Sign-up](/api/enchanted-link/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.'
operationId: SignUpEnchantedLink
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkSignUpEmailRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: EnchantedLink
x-order: 1
x-meta:
title: Sign-Up | Enchanted Link
description: Sign-up new end user by sending an enchanted link via email
keywords: api, enchanted link
/v1/auth/enchantedlink/signin/email:
post:
tags:
- ''
summary: Sign-In
description: '### Sign-in existing user by sending an enchanted link via email
Initiate a sign-in process by sending an enchanted link to a new end user.
Descope will generate and deliver 3 clickable links to the email address specified,
each is numbered with random 2 digit number. When you initiate the enchanted link, the `linkId` will be returned. This `linkId` needs to be displayed to the user to indicate which link for the user to click
once they receive the email. Only when the correct link is clicked will the user be successfully verified and logged in.
Each clickable link is made up of two parts -
the URI you provide in the `URI` field and the enchanted link token generated by Descope.
For example, if `URI=https://app.mycompany.com/enchantedlink/verify`,
the clickable enchanted link will be `https://app.mycompany.com/enchantedlink/verify?t=enchanted-link-token.`
Enchanted links expire in the time frame configured in the
[Descope console](https://app.descope.com/settings/authentication/enchantedlink),
so sending multiple enchanted links (for example, when an end user tries to sign-up a second or third time)
does not invalidate links that have already been sent.
The return body will include `linkId` and `pendigRef`.
The `linkId` (a 2 digit number) should be presented to the user,
so they will know which link to click in the delivered email.
The endpoint will return a failure code if the email address is already registered.
Note that `URI` is an optional parameter. If omitted - the project setting will apply.
If provided - it should to be part of the allowed `Approved Domains` configured in the project settings.
### Next Steps
1. Verify the enchanted link token using the [Verify Token](/api/enchanted-link/verify-token) endpoint.
2. Poll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint.
### See Also
- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.
- See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.
- Use the [Sign-Up](/api/enchanted-link/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/enchanted-link/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.'
operationId: SignInEnchantedLinkEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: EnchantedLink
x-order: 2
x-meta:
title: Sign-In | Enchanted Link Email
description: Sign-in existing user by sending an enchanted link via email Email
keywords: api, enchanted link, email
/v1/auth/enchantedlink/signup-in/email:
post:
tags:
- ''
summary: Sign-In with Auto Sign-Up
description: '### Sign-in end user (with automatic sign-up) by sending an enchanted link via email
Initiate a process that implements both sign-in and sign-up using a single endpoint.
If the email address is already registered (the end user has already registered) the user will be signed in.
If the email address is not registered (the end user is not yet registered) the user will be signed up.
Descope will generate and deliver 3 clickable links to the email address specified,
each is numbered with random 2 digit number. When you initiate the enchanted link, the `linkId` will be returned. This `linkId` needs to be displayed to the user to indicate which link for the user to click
once they receive the email. Only when the correct link is clicked will the user be successfully verified and logged in.
Each clickable link is made up of two parts -
the URI you provide in the `URI` field and the enchanted link token generated by Descope.
For example, if `URI=https://app.mycompany.com/enchantedlink/verify`,
the clickable enchanted link will be `https://app.mycompany.com/enchantedlink/verify?t=enchanted-link-token.`
Enchanted links expire in the time frame configured in the
[Descope console](https://app.descope.com/settings/authentication/enchantedlink),
so sending multiple enchanted links (for example, when an end user tries to sign-up a second or third time)
does not invalidate links that have already been sent.
The return body will include `linkId` and `pendigRef`.
The `linkId` (a 2 digit number) should be presented to the user,
so they will know which link to click in the delivered email.
The endpoint will return a failure code if the email address is already registered.
Note that `URI` is an optional parameter. If omitted - the project setting will apply.
If provided - it should to be part of the allowed `Approved Domains` configured in the project settings.
### Next Steps
1. Verify the enchanted link token using the [Verify Token](/api/enchanted-link/verify-token) endpoint.
2. Poll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint.
### See Also
- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.
- See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.
- Use the [Sign-Up](/api/enchanted-link/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/enchanted-link/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.'
operationId: SignUpOrInEnchantedLinkEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: EnchantedLink
x-order: 3
x-meta:
title: Sign-In with Auto Sign-Up | Enchanted Link Email
description: Sign-in end user (with automatic sign-up) by sending an enchanted link via email Email
keywords: api, enchanted link, email
/v1/auth/enchantedlink/verify:
post:
tags:
- ''
summary: Verify Token
description: "### Verify Enchanted Link token from user\n\nVerify that the enchanted link token in the URL clicked by the end user matches and has\nnot expired. This endpoint completes the enchanted link flow for:\n* sign up\n * [Sign-Up via email](/api/enchanted-link/sign-up)\n* sign-in\n * [Sign-In via email](/api/enchanted-link/sign-in)\n* sign-in with auto sign-up\n * [Sign-In with Auto Sign-up via email](/api/enchanted-link/sign-in-auto-sign-up)\n* Update data\n * [update email](/api/enchanted-link/update-email)\n\n### Next Steps\n\nPoll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint.\n\nThe response object will be empty when this endpoint completes successfully. The session information will be returned by the the [Poll Session](/api/enchanted-link/poll-session) endpoint.\n\n### See Also\n- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.\n- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number."
operationId: VerifyEnchantedLink
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyEnchantedLinkRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyEnchantedLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: EnchantedLink
x-order: 4
x-meta:
title: Verify Token | Enchanted Link
description: Verify Enchanted Link token from user
keywords: api, enchanted link
/v1/auth/enchantedlink/pending-session:
post:
tags:
- ''
summary: Poll Session
description: '### Poll user session for successful completion of token verification
This endpoint is used to wait for the enchanted link verification by the end user.
Use this endpoint in a poling way, until it returns a successful JWT, or timeout error.
The response object includes the session JWT `sessionJwt` and refresh JWT `refreshJwt`
when this endpoint completes successfully.
### See Also
- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.'
operationId: GetEnchantedLinkSession
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnchantedLinkSessionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JWTResponse'
security:
- Descope Project ID: []
x-publishYaml: EnchantedLink
x-order: 5
x-meta:
title: Poll Session | Enchanted Link
description: Poll user session for successful completion of token verification
keywords: api, enchanted link
/v1/auth/enchantedlink/update/email:
post:
tags:
- ''
summary: Update Email
description: '### Update email of end user by sending enchanted link via email
Update the email address of an existing end user by sending an enchanted link to the new email address.
Descope will generate and deliver 3 clickable links to the email address specified,
each is numbered with random 2 digit number.
Only the right link (based on the number returned will be successfully verified when clicked)
Each clickable link is made up of two parts -
the URI you provide in the `URI` field and the enchanted link token generated by Descope.
For example, if `URI=https://app.mycompany.com/enchantedlink/verify`,
the clickable enchanted link will be `https://app.mycompany.com/enchantedlink/verify?t=enchanted-link-token.`
Enchanted links expire in the time frame configured in the
[Descope console](https://app.descope.com/settings/authentication/enchantedlink),
so sending multiple enchanted links (for example, when an end user tries to sign-up a second or third time)
does not invalidate links that have already been sent.
The bearer token requires both the ProjectId and refresh JWT in the format `<Project ID>:<JWT>`, and can therefore only be run for end users who are currently signed-in.
Note that `URI` is an optional parameter. If omitted - the project setting will apply.
If provided - it should to be part of the allowed `Approved Domains` configured in the project settings.
Once the token is successfully verified - the email address will be updated.
Descope allows you to associating multiple login IDs for a user during API update calls. For details on how this feature works, please review the details [here](/manage/users#associating-multiple-login-ids-for-a-user).
### Next Steps
1. Verify the enchanted link token using the [Verify Token](/api/enchanted-link/verify-token) endpoint.
2. Poll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint.
### See Also
- See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links.
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number.'
operationId: UpdateUserEmailEnchantedLink
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserEmailEnchantedLinkRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnchantedLinkResponse'
security:
- Descope Project ID:Refresh JWT: []
x-publishYaml: EnchantedLink
x-order: 5
x-meta:
title: Update Email | Enchanted Link Email
description: Update email of end user by sending enchanted link via email Email
keywords: api, enchanted link, email
/v1/auth/notp/{provider}/signup:
post:
tags:
- ''
summary: Sign-Up
description: Create a new user using NOTP
operationId: SignUpNOTP
parameters:
- name: provider
in: path
description: Whatsapp, IMessage, etc
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPSignUpRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: NOTP
x-order: 1
x-meta:
title: Sign-Up | NOTP
description: Create a new user using NOTP
keywords: api, notp
/v1/auth/notp/{provider}/signin:
post:
tags:
- ''
summary: Sign-In
description: Login a user using NOTP
operationId: SignInNOTP
parameters:
- name: provider
in: path
description: Whatsapp, IMessage, etc
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: NOTP
x-order: 2
x-meta:
title: Sign-In | NOTP
description: Login a user using NOTP
keywords: api, notp
/v1/auth/notp/{provider}/signup-in:
post:
tags:
- ''
description: Login in using NTOP. If the user does not exist, a new user will be created with the given identifier
operationId: SignUpOrInNOTP
parameters:
- name: provider
in: path
description: Whatsapp, IMessage, etc
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NOTPLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: NOTP
x-order: 3
summary: Sign-In with Auto Sign-Up
x-meta:
title: Sign-In with Auto Sign-Up | NOTP
description: Login in using NTOP. If the user does not exist, a new user will be created with the given identifier
keywords: api, notp
/v1/auth/notp/pending-session:
post:
tags:
- ''
summary: Get NoTP Pending Session
description: Get a session that was generated by NOTP Sign in / Sign up request, and verified with Verify request
operationId: GetNOTPSession
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetNOTPSessionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JWTResponse'
security:
- Descope Project ID: []
x-publishYaml: NOTP
x-order: 4
x-meta:
title: Get NoTP Pending Session | NOTP
description: Get a session that was generated by NOTP Sign in / Sign up request, and verified with Verify request
keywords: api, notp
components:
schemas:
NOTPLinkResponse:
type: object
properties:
pendingRef:
type: string
description: Pending ref is the reference to the pending operation
redirectUrl:
type: string
description: Link to the app (e.g. https://wa.me/1234567890?text=My%20authentication%20code%20is%20999999)
image:
type: string
description: QR code image
UpdateUserEmailEnchantedLinkRequest:
type: object
properties:
loginId:
type: string
email:
type: string
redirectUrl:
type: string
addToLoginIDs:
type: boolean
default: false
onMergeUseExisting:
type: boolean
default: false
providerId:
type: string
templateOptions:
type: object
additionalProperties:
type: string
locale:
type: string
failOnConflict:
type: boolean
NOTPSignUpRequest:
type: object
properties:
provider:
type: string
description: Whatsapp, IMessage, etc
phone:
type: string
loginId:
type: string
user:
$ref: '#/components/schemas/SignUpUser'
providerId:
type: string
templates:
$ref: '#/components/schemas/NOTPTemplateIDs'
ssoAppId:
type: string
loginOptions:
$ref: '#/components/schemas/SignupLoginOptions'
GetNOTPSessionRequest:
type: object
properties:
pendingRef:
type: string
JWTResponse:
type: object
properties:
sessionJwt:
type: string
refreshJwt:
type: string
cookieDomain:
type: string
cookiePath:
type: string
cookieMaxAge:
type: integer
format: int32
cookieExpiration:
type: integer
format: int32
user:
$ref: '#/components/schemas/ResponseUser'
firstSeen:
type: boolean
idpResponse:
$ref: '#/components/schemas/IDPResponse'
sessionExpiration:
type: integer
format: int32
externalToken:
type: string
claims:
type: object
tenantSSOID:
type: string
trustedDeviceJwt:
type: string
nextRefreshSeconds:
type: integer
format: int32
cookieName:
type: string
sessionCookieName:
type: string
sessionCookieDomain:
type: string
unsavedSSO:
type: boolean
description: 'NOTE: if you add a new field to this message, also add it to the OptionalJWTResponse message'
NOTPSignInRequest:
type: object
properties:
provider:
type: string
description: Whatsapp, IMessage, etc
loginId:
type: string
description: Optional, becasue can be retrived from the provider webhook
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
templates:
$ref: '#/components/schemas/NOTPTemplateIDs'
ssoAppId:
type: string
SignUpUser:
type: object
properties:
loginId:
type: string
name:
type: string
phone:
type: string
email:
type: string
givenName:
type: string
middleName:
type: string
familyName:
type: string
recoveryEmail:
type: string
recoveryPhone:
type: string
EnchantedLinkSignUpEmailRequest:
type: object
properties:
email:
type: string
loginId:
type: string
user:
$ref: '#/components/schemas/SignUpUser'
redirectUrl:
type: string
providerId:
type: string
loginOptions:
$ref: '#/components/schemas/SignupLoginOptions'
IDPResponse:
type: object
properties:
samlResponse:
type: string
samlGeneratedUser:
type: string
samlGeneratedRoles:
type: string
oidcResponse:
type: string
oidcGeneratedUser:
type: string
oidcGeneratedRoles:
type: string
idpGroups:
type: array
items:
type: string
idpSAMLAttributes:
type: object
default: false
idpOIDCClaims:
type: object
NOTPTemplateIDs:
type: object
properties:
verifyTemplateId:
type: string
successTemplateId:
type: string
errorTemplateId:
type: string
description: NOTP Requests & Responses
EnchantedLinkResponse:
type: object
properties:
pendingRef:
type: string
linkId:
type: string
maskedEmail:
type: string
LoginOptions:
type: object
properties:
stepup:
type: boolean
default: false
customClaims:
type: object
description: Custom claims to include in the JWT as key-value pairs. Keys must be strings; values can be strings, numbers, or booleans.
additionalProperties:
type: string
example:
claim-name: claim-value
mfa:
type: boolean
default: false
ssoAppId:
type: string
templateOptions:
type: object
additionalProperties:
type: string
locale:
type: string
pkceChallenge:
type: string
description: relevant only for enchanted links in the point in time - other methods will ignore this field
format: bytes
revokeOtherSessions:
type: boolean
revokeOtherSessionsTypes:
type: array
items:
type: string
tenantId:
type: string
UserTenants:
type: object
properties:
tenantId:
type: string
roleNames:
type: array
items:
type: string
tenantName:
type: string
permissions:
type: array
items:
type: string
GetEnchantedLinkSessionRequest:
type: object
properties:
pendingRef:
type: string
VerifyEnchantedLinkResponse:
type: object
properties: {}
EnchantedLinkSignInRequest:
type: object
properties:
loginId:
type: string
redirectUrl:
type: string
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
ssoAppId:
type: string
useRecovery:
type: boolean
VerifyEnchantedLinkRequest:
type: object
properties:
token:
type: string
pkceVerifier:
type: string
format: bytes
ResponseUser:
type: object
properties:
loginIds:
type: array
items:
type: string
userId:
type: string
name:
type: string
email:
type: string
phone:
type: string
verifiedEmail:
type: boolean
verifiedPhone:
type: boolean
roleNames:
type: array
items:
type: string
userTenants:
type: array
items:
$ref: '#/components/schemas/UserTenants'
status:
type: string
externalIds:
type: array
items:
type: string
picture:
type: string
test:
type: boolean
default: false
customAttributes:
type: object
description: Custom attributes as key-value pairs. Keys must be strings; values can be strings, numbers, booleans, or arrays.
additionalProperties:
type: string
example:
attribute-key: attribute-value
createdTime:
type: integer
format: int32
TOTP:
type: boolean
default: false
SAML:
type: boolean
default: false
OAuth:
type: object
additionalProperties:
type: boolean
default: false
webauthn:
type: boolean
password:
type: boolean
ssoAppIds:
type: array
items:
type: string
givenName:
type: string
middleName:
type: string
familyName:
type: string
editable:
type: boolean
SCIM:
type: boolean
push:
type: boolean
permissions:
type: array
items:
type: string
OIDC:
type: boolean
consentExpiration:
type: integer
format: int32
recoveryEmail:
type: string
verifiedRecoveryEmail:
type: boolean
recoveryPhone:
type: string
verifiedRecoveryPhone:
type: boolean
SignupLoginOptions:
type: object
properties:
customClaims:
type: object
description: Custom claims to include in the JWT as key-value pairs. Keys must be strings; values can be strings, numbers, or booleans.
additionalProperties:
type: string
example:
claim-name: claim-value
templateOptions:
type: object
additionalProperties:
type: string
locale:
type: string
pkceChallenge:
type: string
description: relevant only for enchanted links in the point in time - other methods will ignore this field
format: bytes
tenantId:
type: string
securitySchemes:
Descope Project ID:
type: http
scheme: bearer
bearerFormat: Project ID
description: Proj
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descope/refs/heads/main/openapi/descope-default-api-openapi.yml