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. On success, you receive a unique code to exchange for a user object in the next step. This endpoint handles both sign-up and sign-in.
- Exchange Code — Call the Exchange Code endpoint to 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 walks the end user through the OAuth provider's authorization and sign-in process. The endpoint takes two arguments:
provider— name of the auth provider (for example,googleorfacebook). For a list of all supported options, see OAuth Providers.redirectURL— destination URL the end user session is redirected to after successfully signing in.
The API response includes url, which the user should be redirected to in order to authenticate with the service provider. Once completed, the user is redirected to the redirectURL with a unique code <code> appended as a URL parameter.
Note that redirectURL is optional. If omitted, the project setting applies. If provided, it must be part of the Approved Domains configured in the project settings.
Exchange Code
In your source code that responds to the 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 returns a valid User Object, which includes the session JWT sessionJwt and refresh JWT refreshJwt.
Use to update phone and validate via enchanted link using SMS POST
Use to update phone and validate via enchanted link using SMS
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.