OAuth2
How to integrate OAuth2 with Sanity
Protip
This OAuth2 integration is intended for technology partners integrating with the Sanity platform.
If you are a prospective or existing customer, please get in touch with your customer representative or contact us via this form.
OAuth2 lets your app request authorization to access private details and perform actions on behalf of a Sanity user through the Sanity API.
To get started, you should talk to us first, as we need to set up your application credentials manually (for the time being). The details we need are
- Name of your application
- A relevant image (URL)
- A short description of your application and the intent to display it to users on the authorized page
- A complete callback URL for your application where we will redirect the user after the authorization is made
- How long the access token should be valid
- If you have several environments (staging, development etc), you will need to provide specific callback URLs for those, too
Our OAuth2 API implements a standard RFC 6749 compatible API using an authorization grant type flow (only).
First, the user must authorize your application. Your app should redirect users to the following URL:
GET https://api.sanity.io/v2021-06-07/auth/oauth/authorize
You need to pass the following values as query parameters:
REQUIREDclient_idstring
ID of your application.
statestring
Random string to be passed back upon completion. It is used to protect against CSRF attacks.
REQUIREDredirect_uristring
URL to redirect user back to. Must match the URL in the Oauth2 app configuration.
If the user grants your request (a view on our side), we redirect back to your site with a code parameter and the state parameter you provided in the previous step.
Gotcha
The process should be aborted if the states do not match.
If the state matches, you can now exchange the authorization code for an access token using the following endpoint:
POST https://api.sanity.io/v2021-06-07/auth/oauth/token
The endpoint requires the following values in the request body as application/x-www-form-urlencoded
REQUIREDclient_idstring
ID of your application.
REQUIREDclient_secretstring
Secret of your application.
REQUIREDcodestring
The code you received.
REQUIREDredirect_uristring
URL to redirect user back to. Must match the URL in the Oauth2 app configuration.
REQUIREDgrant_typestring
Oauth2 grant type. The only accepted value is
authorization_code.
You'll receive a JSON response containing an access_token:
{
"access_token": "skSij3rj23jwoi3j8942u349823ye2389eu2389eu23",
"token_type": "bearer",
"expires_in": 3600
}The expires_in is the lifetime in seconds of the access token.
The access token allows you to make requests to the API on a behalf of a user, by providing the token in the Authorization header (bearer).
In addition to the standard endpoints, we also provide an endpoint to check the state of an access token, which is handy if you want to validate and check if you should renew it. Renewing is done by making the user re-authenticate, as we don't support refresh tokens.
GET https://api.sanity.io/v2021-06-07/auth/oauth/tokens/:token
This should be done server side, as the endpoint will not accept CORS requests, and you should never leak the access tokens out in the the client's browser.
User info can be obtained with using an authenticated request to this endpoint:
GET https://api.sanity.io/v2021-06-07/users/me
{
"id": "g3r2dfwer3",
"name": "Some Person",
"email": "[email protected]",
"profileImage": "https://lh3.googleusercontent.com/a-/2dsfdsfewf23",
"provider": "google"
}We have made a Passport.js strategy for Sanity available in the NPM module passport-sanity