openapi: 3.0.3
info:
title: Descope Apps Text Message (SMS) 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: Text Message (SMS)
paths:
/v1/auth/magiclink/signup/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-Up
description: '### Sign-up new end user by sending a magic link via SMS
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 phone number 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) 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/sms/sign-up) endpoint to sign-in an existing end user.
- Use the [Sign-In with Auto Sign-up](/api/magic-link/sms/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: SignUpMagicLinkSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignUpPhoneRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 1
x-meta:
title: Sign-Up | Magic Link SMS
description: Sign-up new end user by sending a magic link via SMS SMS
keywords: api, magic link, sms
/v1/auth/magiclink/signin/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-In
description: '### Sign-in existing end user by sending a magic link via SMS
Initiate a sign-in process by sending a magic link to an existing end user. Descope will generate and deliver a clickable magic link as an SMS to the phone number 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) 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/sms/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/magic-link/sms/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: SignInMagicLinkSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 2
x-meta:
title: Sign-In | Magic Link SMS
description: Sign-in existing end user by sending a magic link via SMS SMS
keywords: api, magic link, sms
/v1/auth/magiclink/signup-in/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-In with Auto Sign-up
description: '### Sign-in end user (with automatic sign-up) by sending a magic link via SMS
Initiate a process that implements both sign-in and sign-up using a single endpoint. Descope will generate and deliver a clickable magic link as an SMS to the phone number specified. If the phone number 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) 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/sms/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/sms/sign-in) endpoint if you want a sign-in flow that will fail if the end user isn''t yet registered.'
operationId: SignUpOrInMagicLinkSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MagicLinkSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneMagicLinkResponse'
security:
- Descope Project ID: []
x-publishYaml: MagicLink
x-order: 3
x-meta:
title: Sign-In with Auto Sign-up | Magic Link SMS
description: Sign-in end user (with automatic sign-up) by sending a magic link via SMS SMS
keywords: api, magic link, sms
/v1/auth/magiclink/update/phone/sms:
post:
tags:
- Text Message (SMS)
summary: Update Phone Number
description: '### Update phone number of end user by sending magic link via SMS
Update the phone number of an existing end user by sending a magic link to the new phone number. Descope will generate and deliver a clickable magic link as an SMS to the new phone number specified. After successfully verifying the magic link token the new phone number will be used to deliver new magic links via SMS.
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 Step
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: UpdateUserPhoneMagicLinkSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserPhoneMagicLinkRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneMagicLinkResponse'
security:
- Descope Project ID:Refresh JWT: []
x-publishYaml: MagicLink
x-order: 5
x-meta:
title: Update Phone Number | Magic Link SMS
description: Update phone number of end user by sending magic link via SMS SMS
keywords: api, magic link, sms
/v1/auth/otp/signup/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-Up
description: '### Sign-up new end user by sending an OTP code via SMS
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 via SMS to the phone number 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 phone number is already registered.
### Next Steps
Verify the OTP code using the [Verify OTP Code](/api/otp/sms/verify-otp) endpoint to complete the user sign-up process. After successfully verifying the 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 address and phone number.
- Use the [Sign-In](/api/otp/sms/sign-in) endpoint to sign-in an existing end user.
- Use the [Sign-In with Auto Sign-up](/api/otp/sms/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: SignUpOtpSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignUpPhoneRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 1
x-meta:
title: Sign-Up | OTP SMS
description: Sign-up new end user by sending an OTP code via SMS SMS
keywords: api, otp, sms
/v1/auth/otp/signin/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-In
description: '### Sign-in existing end user by sending an OTP code via SMS
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 phone number 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 phone number is not yet registered.
### Next Steps
Verify the OTP code using the [Verify OTP Code](/api/otp/sms/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/sms/sign-up) endpoint to sign-up a new end user.
- Use the [Sign-In with Auto Sign-up](/api/otp/sms/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: SignInOTPSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 2
x-meta:
title: Sign-In | OTP SMS
description: Sign-in existing end user by sending an OTP code via SMS SMS
keywords: api, otp, sms
/v1/auth/otp/signup-in/sms:
post:
tags:
- Text Message (SMS)
summary: Sign-In with Auto Sign-up
description: '### Sign-in end user (with automatic sign-up) by sending an OTP code via SMS
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 SMS. If the phone number is already registered (the end user exists) the user will be signed in. If the phone number 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/sms/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/sms/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/sms/sign-in-auto-sign-up) endpoint if you want a sign-in flow that will fail if the end user isn''t yet registered.'
operationId: SignUpOrInOTPSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OTPSignInRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneOperationResponse'
security:
- Descope Project ID: []
x-publishYaml: OTP
x-order: 3
x-meta:
title: Sign-In with Auto Sign-up | OTP SMS
description: Sign-in end user (with automatic sign-up) by sending an OTP code via SMS SMS
keywords: api, otp, sms
/v1/auth/otp/verify/sms:
post:
tags:
- Text Message (SMS)
summary: Verify OTP Code
description: '### Verify the validity of an OTP code via SMS
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 SMS flow for:
- [Sign-Up](/api/otp/sms/sign-up)
- [Sign-In](/api/otp/sms/sign-in)
- [Sign-In with Auto Sign-up](/api/otp/sms/sign-in-auto-sign-up)
- [Update Email](/api/otp/sms/update-phone)
The response object includes the session JWT `sessionJwt` and refresh JWT `refreshJwt` when it completes successfully, and the end user will be signed in. For an update phone number flow, the new phone number will replace the original phone number.
### 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: VerifyCodeSMS
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 SMS
description: Verify the validity of an OTP code via SMS SMS
keywords: api, otp, sms
/v1/auth/otp/update/phone/sms:
post:
tags:
- Text Message (SMS)
summary: Update Phone
description: '### Update phone number of Existing User
Update the phone number of an existing end user by sending an OTP code to the new phone number. After successfully verifying the code the new phone number will be used to deliver new OTP messages via SMS. 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/sms/verify-otp) endpoint to complete the update process.
After successfully verifying the code the newphone number will replace the original phone number.
### 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.
- Successful execution will return an empty body
- To try this endpoint - need to provide `Project ID:Refresh JWT` as bearer. You can acquire the Session JWT by signing in the user and collecting it from the response.'
operationId: UpdateUserPhoneOTPSMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserPhoneOTPRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneOperationResponse'
security:
- Descope Project ID:Refresh JWT: []
x-publishYaml: OTP
x-order: 5
x-meta:
title: Update Phone | OTP SMS
description: Update phone number of Existing User SMS
keywords: api, otp, sms
components:
schemas:
PhoneSignUpUserObject:
type: object
properties:
username:
type: string
description: Username Username
name:
type: string
description: Name Name
email:
type: string
description: Email Email
icon:
type: string
UpdateUserPhoneMagicLinkRequest:
type: object
properties:
loginId:
type: string
phone:
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
MagicLinkSignUpPhoneRequest:
type: object
properties:
phone:
type: string
loginId:
type: string
user:
$ref: '#/components/schemas/SignUpUser'
redirectUrl:
type: string
providerId:
type: string
loginOptions:
$ref: '#/components/schemas/SignupLoginOptions'
PhoneMagicLinkResponse:
type: object
properties:
maskedPhone:
type: string
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
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
OTPSignInRequest:
type: object
properties:
loginId:
type: string
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
ssoAppId:
type: string
useRecovery:
type: boolean
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'
PhoneOperationResponse:
type: object
properties:
maskedPhone:
type: string
verificationAttempts:
type: integer
format: int32
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
OTPSignUpPhoneRequest:
type: object
properties:
phone:
type: string
loginId:
type: string
user:
$ref: '#/components/schemas/PhoneSignUpUserObject'
providerId:
type: string
loginOptions:
$ref: '#/components/schemas/SignupLoginOptions'
OTPVerifyCodeRequest:
type: object
properties:
loginId:
type: string
code:
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
MagicLinkSignInRequest:
type: object
properties:
loginId:
type: string
redirectUrl:
type: string
loginOptions:
$ref: '#/components/schemas/LoginOptions'
providerId:
type: string
ssoAppId:
type: string
useRecovery:
type: boolean
UpdateUserPhoneOTPRequest:
type: object
properties:
loginId:
type: string
phone:
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
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
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 Projec
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descope/refs/heads/main/openapi/descope-text-message-sms-api-openapi.yml