Social Login (OAuth) APIs
Use the Social Login (OAuth) APIs to let your end users sign-in to your app or website using their existing social network credentials, for example Google or Facebook.
Overview
Implementing OAuth using the APIs is a two step process:
- Authorize - Call the Sign-Up / Sign-In endpoint to authorize your end user to sign-up or sign-in using their OAuth credentials. After the end user has successfully signed-in you will get a unique code, which will be exchanged for a user object in the next step. This endpoint is used for both sign-up and sign-in.
- Exchange Code - call the Exchange Code endpoint which will exchange the unique code for a user object, which includes the session JWT
sessionJwtand refresh JWTrefreshJwt.
Implementing OAuth
Authorize sign-up/sign-in
Call the Sign-Up / Sign-In endpoint to authorize your end user to sign-up or sign-in using their social network credentials. Descope will walk the end user through the OAuth provider's authorization and sign-in process. The endpoint takes two arguments:
provider- name of Auth provider (for example, "google" or "facebook"). For list of all supported options see here.redirectURL- destination URL you want the end user session to be redirected to after successfully signing in
The API response includes url, which the user should be redirect to in order to perform the OAuth authentication with the service provider. Once completed, the user will be redirected to the redirectURL with a unique code <code> appended as a URL parameter.
Note that redirectURL is an optional parameter. If omitted - the project setting will apply. If provided - it should to be part of the Approved Domains configured in the project settings.
Exchange Code
In your source code that responds to user session being redirected to redirectUrl, exchange the unique code <code> from the URL parameter for a Descope user object.
- Extract the unique code
<code>from the URL parameter. - Call the Exchange Code endpoint.
The endpoint response will return a valid User Object, which includes the session JWT sessionJwt and refresh JWT refreshJwt.
Update Email POST
### 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 `<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. 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. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID:Refresh JWT>`
Sign-Up / Sign-In POST
### Authorize end user to sign-up or sign-in using social login credentials Initiate a social login (OAuth) sign-up or sign-in process for an end user. Descope will coordinate the authorization process with the OAUth provider specified in the `provider` field. Specify the URL you want to redirect the end user to after a successful sign-in in the `redirectURL` parameter. When the OAuth authorization completes successfully, the endpoint returns a URL `url` that has a unique code `<unique-code\>` appended as a URL parameter to the `redirectURL` you provided. For example, if `redirectURL = https://oauth.mycompany.com/shopping.htm` then `url = https://oauth.mycompany.com/shopping.htm?code=<unique-code\>`. The unique code will be exchanged for a valid user object in the next step. After the end user successfully authenticates with the OAuth provider the end user session is redirected to `url`. ### Next Steps Call the [Exchange Code](/api/oauth/exchange-code) endpoint from the flow that responds to the URL specified in the `redirectURL` field, to exchange the unique code for a user session object. ### 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. - See [User Login Options](/api/overview#user-login-options) for further details on the stepup, mfa, and customClaims parameters. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID>`