openapi: 3.0.3
info:
title: Descope Apps Email 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: Email
paths:
/v1/auth/magiclink/signup/email:
post:
tags:
- Email
summary: Sign-Up
description: '### Sign-up new end user by sending a magic link via email
Initiate a sign-up process by sending a magic link to a new end user. Descope will generate and deliver a clickable magic link to the email address specified. The clickable magic link is made up of two parts - the URI you provide in the `URI` field and the magic link token generated by Descope. For example, if `URI=https://app.mycompany.com/magiclink/verify`, the clickable magic link will be `https://app.mycompany.com/magiclink/verify?t=magic-link-token.` Magic links expire in the time frame configured in the [Descope console](https://app.descope.com/settings/authentication/magiclink), so sending multiple magic links (for example, when an end user tries to sign-up a second or third time) does not invalidate magic links that have already been sent.
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
Verify the magic link token using the [Verify Token](/api/magic-link/verification/verify-token) endpoint.
### See Also
- See [Magic link Authentication](/auth-methods/magic-link/with-sdks/client#introduction) for details about implementing magic 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/magic-link/email/sign-in) endpoint to sign-in an existing end user.
- Use the [Sign-In with Auto Sign-up](/api/magic-link/email/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: SignUpMagicLinkEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignUpEmailRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 1
x-meta:
title: Sign-Up | Magic Link Email
description: Sign-up new end user by sending a magic link via email Email
keywords: api, magic link, email
/v1/auth/magiclink/signin/email:
post:
tags:
- Email
summary: Sign-In
description: '### Sign-in existing end user by sending a magic link via email
Initiate a sign-in process by sending a magic link to an existing end user. Descope will generate and deliver a clickable magic link to the email address specified. The clickable magic link is made up of two parts - the URI you provide in the `URI` field and the magic link token generated by Descope. For example, if `URI=https://app.mycompany.com/magiclink/verify`, the clickable magic link will be `https://app.mycompany.com/magiclink/verify?t=magic-link-token.` Magic links expire in the time frame configured in the [Descope console](https://app.descope.com/settings/authentication/magiclink), so sending multiple magic links (for example, when an end user tries to sign-up a second or third time) does not invalidate prior magic links that have already been sent.
The endpoint will return a failure code if the email address is not 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
Verify the magic link token using the [Verify Token](/api/magic-link/verification/verify-token) endpoint.
### See Also
- See [Magic link Authentication](/auth-methods/magic-link/with-sdks/client#introduction) for details about implementing magic 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/magic-link/email/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/magic-link/email/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: SignInMagicLinkEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 2
x-meta:
title: Sign-In | Magic Link Email
description: Sign-in existing end user by sending a magic link via email Email
keywords: api, magic link, email
/v1/auth/magiclink/signup-in/email:
post:
tags:
- Email
summary: Sign-In with Auto Sign-up
description: '### Sign-in end user (with automatic sign-up) by sending a magic link via email
Initiate a process that implements both sign-in and sign-up using a single endpoint. Descope will generate and deliver a clickable magic link to the email address specified. 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.
The clickable magic link is made up of two parts - the URI you provide in the `URI` field and the magic link token generated by Descope. For example, if `URI=https://app.mycompany.com/magiclink/verify`, the clickable magic link will be `https://app.mycompany.com/magiclink/verify?t=magic-link-token.` Magic links expire in the time frame configured in the [Descope console](https://app.descope.com/settings/authentication/magiclink), so sending multiple magic links (for example, when an end user tries to sign-up a second or third time) does not invalidate prior magic links that have already been sent.
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
Verify the magic link token using the [Verify Token](/api/magic-link/verification/verify-token) endpoint.
### See Also
- See [Magic link Authentication](/auth-methods/magic-link/with-sdks/client#introduction) for details about implementing magic 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/magic-link/email/sign-up) endpoint if you want a sign-up flow that will fail if the end user is already registered.
- Use the [Sign-In](/api/magic-link/email/sign-in) endpoint if you want a sign-in flow that will fail if the end user isn''t yet registered.'
operationId: SignUpOrInMagicLinkEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 3
x-meta:
title: Sign-In with Auto Sign-up | Magic Link Email
description: Sign-in end user (with automatic sign-up) by sending a magic link via email Email
keywords: api, magic link, email
/v1/auth/magiclink/update/email:
post:
tags:
- Email
summary: Update Email
description: '### Update email of end user by sending magic link via email
Update the email address of an existing end user by sending a magic link to the new email address. Descope will generate and deliver a clickable magic link to the new email address specified. After successfully verifying the magic link token the new email address will be used to deliver new magic links via email.
The clickable magic link is made up of two parts - the URI you provide in the `URI` field and the magic link token generated by Descope. For example, if `URI=https://app.mycompany.com/magiclink/verify`, the clickable magic link will be `https://app.mycompany.com/magiclink/verify?t=magic-link-token.` Magic links expire in the time frame configured in the [Descope console](https://app.descope.com/settings/authentication/magiclink), so sending multiple magic links (for example, when an end user tries to sign-up a second or third time) does not invalidate prior magic 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.
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
Verify the magic link token using the [Verify Token](/api/magic-link/verification/verify-token) endpoint.
### See Also
- See [Magic link Authentication](/auth-methods/magic-link) for details about implementing magic 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: UpdateUserEmailMagicLink
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserEmailMagicLinkRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMagicLinkResponse'
security:
- Descope Project ID:Refresh JWT: []
x-publishYaml: MagicLink
x-order: 5
x-meta:
title: Update Email | Magic Link Email
description: Update email of end user by sending magic link via email Email
keywords: api, magic link, email
/v1/auth/otp/signup/email:
post:
tags:
- Email
summary: Sign-Up
description: '### Sign-up new end user by sending an OTP code via email
Initiate a sign-up process by sending a One-Time Password (OTP) to a new end user. Descope will generate and deliver the OTP code to the email address specified. Sending multiple OTP codes (for example, when an end user tries to sign-up a second or third time) will invalidate any OTP code that has already been sent.
This endpoint will return an empty response object when it completes successfully. The endpoint will return a failure code if the email address is already registered.
### Next Steps
Verify the OTP code using the [Verify OTP Code](/api/otp/email/verify-otp) endpoint to complete the user sign-up process. After successfully verifying OTP code the end user will be signed-in.
### See Also
- 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/otp/email/sign-in) endpoint to sign-in an existing end user.
- Use the [Sign-In with Auto Sign-up](/api/otp/email/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: UserSignupOtpEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignUpEmailRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 1
x-meta:
title: Sign-Up | OTP Email
description: Sign-up new end user by sending an OTP code via email Email
keywords: api, otp, email
/v1/auth/otp/signin/email:
post:
tags:
- Email
summary: Sign-In
description: '### Sign-in existing end user by sending an OTP code via email
Initiate a sign-in process by sending a One-Time Password (OTP) to an existing end user. Descope will generate and deliver the OTP code to the email address specified. Sending multiple OTP codes (for example, when an end user tries to sign-in a second or third time) will invalidate any OTP code that has already been sent.
This endpoint will return an empty response object when it completes successfully. The endpoint will return a failure code if the email address is not yet registered.
### Next Steps
Verify the OTP code using the [Verify OTP Code](/api/otp/email/verify-otp) endpoint to complete the user sign-in process. After successfully verifying the code the end user will be signed-in.
### See Also
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email address and phone number.
- See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.
- Use the [Sign-Up](/api/otp/email/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/otp/email/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: UserSigninOtpEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 2
x-meta:
title: Sign-In | OTP Email
description: Sign-in existing end user by sending an OTP code via email Email
keywords: api, otp, email
/v1/auth/otp/signup-in/email:
post:
tags:
- Email
summary: Sign-In with Auto Sign-up
description: '### Sign-in end user (with automatic sign-up) by sending an OTP code via email
Initiate a process that implements both sign-in and sign-up using a single endpoint. Descope will generate and deliver the One-Time Password (OTP) to the end user via email. If the email address is already registered (the end user exists) 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. Sending multiple OTP codes (for example, when an end user tries to sign-up/sign-in a second or third time) will invalidate any OTP code that has already been sent.
This endpoint will return an empty response object when it completes successfully.
### Next Steps
Verify the OTP code using the [Verify OTP Code](/api/otp/email/verify-otp) endpoint to complete the user sign-in process.
After successfully verifying the code the end user will be signed-in.
### See Also
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email address and phone number.
- See [User Login Options](/api/overview#user-login-options) for further details on loginOptions.
- Use the [Sign-Up](/api/otp/email/sign-up) endpoint if you want a sign-up flow that will fail if the end user is already registered.
- Use the [Sign-In](/api/otp/email/sign-in) endpoint if you want a sign-in flow that will fail if the end user isn''t yet registered.'
operationId: UserSignUpInOtpEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 3
x-meta:
title: Sign-In with Auto Sign-up | OTP Email
description: Sign-in end user (with automatic sign-up) by sending an OTP code via email Email
keywords: api, otp, email
/v1/auth/otp/verify/email:
post:
tags:
- Email
summary: Verify OTP Code
description: '### Verify the validity of an OTP code sent via email
Verify that the OTP code entered by the end user matches the OTP code that was sent. The Verify OTP code endpoint completes the OTP via email flow for:
- [Sign-Up](/api/otp/email/sign-up)
- [Sign-In](/api/otp/email/sign-in)
- [Sign-In with Auto Sign-up](/api/otp/email/sign-in-auto-sign-up)
- [Update Email](/api/otp/email/update-email)
The response object includes the session JWT `sessionJwt` and refresh JWT `refreshJwt` when the endpoint completes successfully, and the end user will be signed in. For an update email flow, the new email address will replace the original email address.
### See Also
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email address and phone number.'
operationId: VerifyOtpEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPVerifyCodeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JWTResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 4
x-meta:
title: Verify OTP Code | OTP Email
description: Verify the validity of an OTP code sent via email Email
keywords: api, otp, email
/v1/auth/otp/update/email:
post:
tags:
- Email
summary: Update Email
description: '### Update Email Address of Existing User
Update the email of an existing end user by sending an OTP code to the new email address. After successfully verifying the code the new email address will be used to deliver new OTP messages via email. 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.
This endpoint will return an empty response object when it completes successfully.
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
Verify the OTP code using the [Verify OTP Code](/api/otp/email/verify-otp) endpoint to complete the update process.
After successfully verifying the code the new email address will replace the original email address.
### See Also
- See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email address and phone number.
- See the [Verify OTP Code](/api/otp/email/verify-otp) endpoint, which will return the Refresh Jwt needed.'
operationId: UpdateUserEmailOtp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserEmailOTPRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailOperationResponse'
security:
- Descope Project ID:Refresh JWT: []
x-publishYaml: OTP
x-order: 5
x-meta:
title: Update Email | OTP Email
description: Update Email Address of Existing User Email
keywords: api, otp, email
/v1/auth/password/reset:
post:
tags:
- Email
summary: Reset Password
description: '### Sent a password reset email to an existing user utilizing the password API.
### Next Steps
You will then need to verify the user after the password reset is sent via email, this would need to be done via [Verify Magic Link](/api/magic-link/verification/verify-token).
### See Also
- 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.
- You can also utilize [Update Password](/api/passwords/update-password) or [Replace Password](/api/passwords/replace-password) as alternatives to change a user''s password.'
operationId: SendPasswordReset
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetSendRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetSendResponse'
security:
- Descope Project ID: []
x-publishYaml: Password
x-order: 3
x-meta:
title: Reset Password | Password
description: Sent a password reset email to an existing user utilizing the password API.
keywords: api, password
components:
schemas:
OTPSignInRequest:
type: object
properties:
loginId:
type: string
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
ssoAppId:
type: string
useRecovery:
type: boolean
MagicLinkSignUpEmailRequest:
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'
MagicLinkSignInRequest:
type: object
properties:
loginId:
type: string
redirectUrl:
type: string
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
ssoAppId:
type: string
useRecovery:
type: boolean
EmailMagicLinkResponse:
type: object
properties:
maskedEmail:
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'
EmailOperationResponse:
type: object
properties:
maskedEmail:
type: string
verificationAttempts:
type: integer
format: int32
UpdateUserEmailOTPRequest:
type: object
properties:
loginId:
type: string
email:
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
PasswordResetSendRequest:
type: object
properties:
loginId:
type: string
redirectUrl:
type: string
providerId:
type: string
templateOptions:
type: object
additionalProperties:
type: string
locale:
type: string
useRecovery:
type: boolean
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
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
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
EmailSignUpUserObject:
type: object
properties:
username:
type: string
description: Username Username
name:
type: string
description: Name Name
phone:
type: string
description: Phone Phone
icon:
type: string
OTPVerifyCodeRequest:
type: object
properties:
loginId:
type: string
code:
type: string
UpdateUserEmailMagicLinkRequest:
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
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:
typ
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descope/refs/heads/main/openapi/descope-email-api-openapi.yml