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 `:`, 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: 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