OAuth2

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:

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.

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

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": "some@email.com",
  "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