authentication

Reference

2 min read

Authentication

Create an Auth Token

post/v3/user/tokens

Creates and returns a new authentication token for the currently authenticated User. The bearerToken property is only provided once, in the response body, so be sure to save it on the client for use with API requests.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/user/tokens?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "SOME_STRING_VALUE",
4    "expiresAt": "SOME_NUMBER_VALUE"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Parameters

Query Params

Body Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

Successful response.

bearerTokenstringRequired
The authentication token's actual value. This token is only provided in this response, and can never be retrieved again in the future. Be sure to save it somewhere safe!
Example: uRKJSTt0L4RaSkiMj41QTkxM

tokenRequired

Response Codes

Code	Description
`200`	Successful response.
`400`	One of the provided values in the request body is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/user/tokens?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "SOME_STRING_VALUE",
4    "expiresAt": "SOME_NUMBER_VALUE"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Delete an authentication token

delete/v3/user/tokens/{tokenId}

Invalidate an authentication token, such that it will no longer be valid for future HTTP requests.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/user/tokens/5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Parameters

Path Params

Path Parameter	Description
tokenId	string required The identifier of the token to invalidate. The special value "current" may be supplied, which invalidates the token that the HTTP request was authenticated with. Example:`5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391`

Response

Authentication token successfully deleted.

tokenIdstringRequired
The unique identifier of the token that was deleted.
Example: 5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391

Response Codes

Code	Description
`200`	Authentication token successfully deleted.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	Token not found with the requested `tokenId`.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/user/tokens/5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Login with email

post/registration

Request a new login for a user to get a token. This will respond with a verification token and send an email to confirm the request. Once confirmed you can use the verification token to get an authentication token.

Optional params

fetch-request

1await fetch("https://api.vercel.com/registration", {
2  "body": {
3    "email": "user@mail.com",
4    "tokenName": "Your Client App Name"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Parameters

Body Params

Body Parameter	Description
email	string required The user email. Example:`"user@mail.com"`
tokenName	string The desired name for the token. It will be displayed on the user account details. Example:`"Your Client App Name"`

Response

One of the following objects
One of

Response Codes

Code	Description
`200`	The request was successful and an email was sent
`400`	One of the provided values in the request body is invalid. The provided email is invalid because the owner is blocked

Optional params

fetch-request

1await fetch("https://api.vercel.com/registration", {
2  "body": {
3    "email": "user@mail.com",
4    "tokenName": "Your Client App Name"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Get Auth Token Metadata

get/v5/user/tokens/{tokenId}

Retrieve metadata about an authentication token belonging to the currently authenticated User.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/user/tokens/5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Path Parameter	Description
tokenId	string required The identifier of the token to retrieve. The special value "current" may be supplied, which returns the metadata for the token that the current HTTP request is authenticated with. Example:`5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391`

Response

Successful response.

tokenRequired

Response Codes

Code	Description
`200`	Successful response.
`400`	One of the provided values in the request query is invalid.
`403`	You do not have permission to access this resource.
`404`	Token not found with the requested `tokenId`.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/user/tokens/5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List Auth Tokens

get/v5/user/tokens

Retrieve a list of the current User's authentication tokens.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/user/tokens", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Response

paginationRequired

testingToken

tokensarrayRequired

Response Codes

Code	Description
`200`
`400`
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/user/tokens", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Verify a login request to get an authentication token

get/registration/verify

Verify the user accepted the login request and get a authentication token. The user email address and the token received after requesting the login must be added to the URL as a query string with the names email and token.

Optional params

fetch-request

1await fetch("https://api.vercel.com/registration/verify?token=SOME_STRING_VALUE&email=SOME_STRING_VALUE&landingPage=SOME_STRING_VALUE&pageBeforeConversionPage=SOME_STRING_VALUE&sessionReferrer=SOME_STRING_VALUE&ssoUserId=SOME_STRING_VALUE&teamName=SOME_STRING_VALUE&teamPlan=pro&teamSlug=SOME_STRING_VALUE&tokenName=Your Client App Name&utmCampaign=SOME_STRING_VALUE&utmMedium=SOME_STRING_VALUE&utmSource=SOME_STRING_VALUE&utmTerm=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
token	string required The token returned when the login was requested.
email	string Email to verify the login.
landingPage	string The page on which the user started their session.
pageBeforeConversionPage	string The page that sent the user to the signup page.
sessionReferrer	string Referrer to the session.
ssoUserId	string The SAML Profile ID, when connecting a SAML Profile to a Team member for the first time.
teamName	string The name of this user's team.
teamPlan	string of the following The plan for this user's team (pro or hobby). Allowed values:`prohobby`
teamSlug	string The slug for this user's team.
tokenName	string The desired name for the token. It will be displayed on the user account details. Example:`Your Client App Name`
utmCampaign	string
utmMedium	string
utmSource	string
utmTerm	string

Response

emailstringRequired
Email address of the authenticated user.
Example: amy@example.com

teamIdstring
When completing SAML Single Sign-On authentication, this will be the ID of the Team that was authenticated for.
Example: team_LLHUOMOoDlqOp8wPE4kFo9pE

tokenstringRequired
The user authentication token that can be used to perform API requests.
Example: 1ioXyz9Ue4xdCYGROet1dlKd

Response Codes

Code	Description
`200`	The verification was successful.
`400`	One of the provided values in the request query is invalid. The slug is already in use The provided token exists but is not yet confirmed
`403`	You do not have permission to access this resource. The verification sso token is invalid or not found The verification token is invalid or not found
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/registration/verify?token=SOME_STRING_VALUE&email=SOME_STRING_VALUE&landingPage=SOME_STRING_VALUE&pageBeforeConversionPage=SOME_STRING_VALUE&sessionReferrer=SOME_STRING_VALUE&ssoUserId=SOME_STRING_VALUE&teamName=SOME_STRING_VALUE&teamPlan=pro&teamSlug=SOME_STRING_VALUE&tokenName=Your Client App Name&utmCampaign=SOME_STRING_VALUE&utmMedium=SOME_STRING_VALUE&utmSource=SOME_STRING_VALUE&utmTerm=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Last updated on April 27, 2024

Upload a cache artifact

Create an Auth Token

Was this helpful?