✨Discover storytelling in the AI age with Pixar's Matthew Luhn at Sanity Connect, May 8th—register now
Experimental feature


How to integrate OAuth2 with Sanity

OAuth2 lets your app request authorization to access private details and perform actions on behalf of a Sanity user through the Sanity API.

In order 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 to users on the authorize 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 spesific 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.


The process should be aborted if the states do not match.

Exchanging code for an access token

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.

Using 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).

Checking the access token

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.

Getting user info

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"

Passport.js strategy

We have made a Passport.js strategy for Sanity available in the NPM module passport-sanity

Was this article helpful?