Introduction to Descope API

The Descope REST API allows implementing user authentication via the different supported methods, with low-level calls from either frontend or backend architectures. The APIs are grouped according to the authentication methods (One-Time Password, Magic Link, Social Login, etc.), with the different communication channels supported for each method (email, text message, etc.).

You can download the Descope API and import it to postman. The API yaml file can be downloaded here.

RESTful calls

API calls are sent to api.descope.com over HTTPS. You can try all APIs with a simple curl command, or use the Try It panel in the API Reference portal for each API endpoint. API responses are standard HTTP responses, with JSON bodies where applicable.

Authentication

Most API endpoints are accepting Bearer token in the Authorization request header. For signing up or signing in users, you'll need to provide the Project ID as the Bearer token. For calls acting on a signed in user (update channel, add biometrics, etc.) - you'll also need to add the Refresh JWT to the token in <Project ID>:<Refresh Jwt> format.

The User Object

Users are stored as simple objects in Descope. Each user is assigned a UID (User ID) that never changes. This UID is internal to Descope, and your app. Users should not be exposed to it (they have no use for it). For identifying themselves, users will use either email or phone number. The system will store those as Login ID, which is also unique for users.

When making an API call for sign-up - you can specify the identifier (email or phone) in the Login ID or in the respective field (email or phone). After successful sign up, the system will also store the identifier as Login ID. Subsequent sign-in requests should be done with the Login ID field populated.

Updating the user's email or phone number, when those are also the user's Login ID will result in updating the Login ID as well to the new value.

User Login Options

When signing in a user, the request can contain additional login options sent with the post request as loginOptions. These options are sent as a json format and can include:

  • stepup (boolean) - adds another secure layer for performing certain actions
  • customClaims (json data for custom claims) - adds data for displaying certain data based on claims associated with the user
  • mfa (boolean) - adds another secure layer to the login process by utilizing a second login option to confirm user identity: SMS, Authenticator, etc.

For stepping up a users login, a user will first need to be signed in and verified. Once you have the user's refresh token, you can utilize the ProjectId:RefreshJwt as the bearer and sign in with step up enabled.

For logging in with mfa, a user will first need to be signed in and verified. Once you have the user's refresh token, you can utilize the ProjectId:RefreshJwt as the bearer and sign in with mfa enabled from another login method (sms, email, etc).

User Login Options Use cases:

  1. Utilizing stepup to secure certain functionality within your application. Ex: Logging into your bank's application, then updating personal information requiring a stepup validation in order to complete this task with increased security layers.
  2. Utilizing custom claims to restrict data based on user privileges. Ex: Displaying different data within a school application based on different types of users. Administrators, Teachers, and Students.
  3. Utilizing MFA to ensure secure login from a user using a public machine or a logging in from a new location. Ex: A user typically logs in from their home location, but when traveling, the application utilizes MFA to validate the user for added security.

Rate Limits

Descope SDKs and API endpoints are rate-limited to maintain stable performance and provide a good experience for all users. Descope may limit requests if it detects an unusual spike in requests or abnormal activity in a specific project or across projects. For example, this can happen in a denial-of-service attack. To avoid hitting the rate limit, ensure your app is optimized to make the least number of requests possible based on the need. If a request breaches the rate limit - an error will be returned, together with Retry-After header, which will specify when to retry the request.

Try It!

The Try it console is available to all API endpoints (on the right side). It will auto-populate your Project ID if you are also logged in to the Descope console in the same browser. You will just need to add the relevant parameters to the call, and that's it.