Authorization Server API
The Authorization Server API exposes a set of endpoints which are used by your application for obtaining, refreshing, revoking, and introspecting tokens, as well querying user info:
| Endpoint | URL |
|---|---|
| Authorization Endpoint | https://vercel.com/oauth/authorize |
| Token Endpoint | https://api.vercel.com/login/oauth/token |
| Revoke Token Endpoint | https://api.vercel.com/login/oauth/token/revoke |
| Token Introspection Endpoint | https://api.vercel.com/login/oauth/token/introspect |
| User Info Endpoint | https://api.vercel.com/login/oauth/userinfo |
These endpoints and other features of the authorization server are advertised at the following well-known URL:
When the user clicks your Sign in with Vercel button, your application should redirect the user to the Authorization Endpoint () with the required parameters.
If the user is not logged in, Vercel will show a login screen and then the consent page to grant or deny the requested permissions. If they have already authorized the app, they will be redirected immediately. After approval, Vercel redirects the user back to your application's with a short lived in the query parameter.
The Authorization Endpoint supports the following parameters:
| Parameter | Required | Description |
|---|---|---|
| Yes | The ID of the App, located in the Manage page of the App. | |
| No | A space-separated list of scopes you're requesting: , , , and . If you pass scopes that aren't configured in your app's Manage settings, they're filtered out. If you don't pass , all scopes configured in your app are included by default. | |
| Yes | The URL used to redirect users back to the application after granting authorization, located in the Manage page of the App under Authorization Callback URLs. | |
| Yes | Must be . | |
| No | A random string generated by the application that is used to protect against replay attacks. The same value will be attached as a claim in the ID Token. | |
| No | A random string generated by the application that is used to protect against CSRF attacks. | |
| Yes | A random string generated by the application for additional protection, based on the PKCE specification. | |
| Yes | Must be . |
In your application create an API Route that saves the , and in cookies and redirects the user to the Authorization Endpoint with the required parameters.
After Vercel redirects the user back to your application's with a , your application should call the Token Endpoint to exchange the for tokens.
The Token Endpoint is used to exchange the returned from the Authorization Endpoint, or a Refresh Token for a new Access Token and Refresh Token pair.
| Parameter | Required | Description |
|---|---|---|
| Yes | Either or . - If the user signs in from the application then should be used. - If the user is already signed in but the Access Token has expired, then should be used. | |
| Yes | The ID of the App located in the Manage page. | |
| Optional | The client secret generated in the Manage page. The parameter is optional if client authentication is set to . Setting is suitable for public applications that cannot securely store secrets, such as SPAs and mobile apps. | |
| No | If is then this parameter is required. The value is obtained during the Authorization Endpoint flow. | |
| No | If is then this parameter is required. It should be the code verifier bound to the from the authorization request. | |
| No | If is then this parameter is required. It should be the same value used in the Authorization Endpoint. | |
| No | If is then this parameter is required. This is the Refresh Token which will be used to obtain a new pair of Access and Refresh tokens. |
The example below shows how to exchange the for tokens in Next.js, validating the and before setting the authentication cookies.
The expected response from the Token Endpoint is a JSON object with the following properties:
Both the Access and Refresh Token can be revoked before expiration if needed. If the Access Token is revoked, the Refresh Token is also revoked. The example below shows how to revoke the Access Token in Next.js.
The token introspection endpoint validates an Access Token or Refresh Token and returns metadata about its state. Use this endpoint to check if a token is active before making API requests.
| Parameter | Required | Description |
|---|---|---|
| Yes | The token to validate (either Access Token or Refresh Token). |
The endpoint returns a JSON response with token metadata:
The example below shows how to validate a token in Next.js:
The user info endpoint returns the consented OpenID claims about the signed-in user. You must authenticate to this endpoint by including an access token as a bearer token in the Authorization header.
The endpoint returns a JSON response with consented OpenID claims:
The example below shows how to request user info in Next.js:
Was this helpful?