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 `:`, 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 `:`, 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: 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 OTPSignUpEmailRequest: type: object properties: email: type: string loginId: type: string user: $ref: '#/components/schemas/EmailSignUpUserObject' providerId: type: string loginOptions: $ref: '#/components/schemas/SignupLoginOptions' PasswordResetSendResponse: type: object properties: resetMethod: type: string pendingRef: type: string linkId: type: string maskedEmail: type: string 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: Project ID as bearer token. Descope Project ID:Refresh JWT: type: http scheme: bearer bearerFormat: Project ID:Refresh JWT description: Project ID:Refresh JWT as bearer token. Descope Project ID:Access Key: type: http scheme: bearer bearerFormat: ProjectId:AccessKey description: Project ID:Access Key as bearer token. Descope Project ID:Session JWT: type: http scheme: bearer bearerFormat: Project ID:Session JWT description: Project ID:Session JWT as bearer token. Descope Project ID and Management Key: type: http description: Project ID:Management Key as bearer token. scheme: bearer bearerFormat: ProjectId:ManagementKey externalDocs: description: Descope Server url: https://docs.descope.com