Authentication
Introduction
Authentication tokens validate API requests made by individuals or integrations to the server. All Server to Server API requests require an authToken
in the header of the request.
Using authentication endpoints, you can:
- Create Server to Server API tokens outside of the B2B Edition control panel.
- View and delete existing API tokens.
- Arrange for your integration to log in a storefront user and gather tokens for future GraphQL requests in the context of a particular Company and user.
- Validate a storefront user’s credentials in order to generate a GQL token.
The Authentication API allows you to create V3 Server to Server and storefront authTokens, but you cannot create tokens for the deprecated V2 Server to Server API. You can create V2 tokens using the API Account settings (opens in a new tab) in the B2B Edition control panel; however, it is not recommended to use V2 endpoints.
Get a Server to Server Token
POST https://api-b2b.bigcommerce.com/api/v3/io/auth/backendRequest
Creates a Server to Server API account with a token to validate future requests made to B2B’s Server to Server APIs.
This endpoint does not require an existing authToken, but you must validate the request with the login credentials of your backend B2B Edition user account. Only users with the pre-built Administrator or Store Owner role are allowed to create API tokens with this endpoint; custom user roles with API account permissions are not supported.
Authentication
- authToken in header
Body
storeHashstring
requiredThe unique store hash for the BigCommerce store.>= 1 charactersExample: 1234abcdemailstring
requiredThe email address associated with the user's account.>= 1 charactersExample: user@example.compasswordstring
requiredThe password associated with the user's account.>= 1 charactersExample: MyPassword123namestring
requiredThe internal name assigned to the generated API token.Example: customer storefront token
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataarray[object]
example
Delete Backend API Tokens
DELETE https://api-b2b.bigcommerce.com/api/v3/io/auth/backendRequest
Deletes an existing Server to Server API token by specifying its ID. You can get a token’s ID using the Get All Server to Server Tokens endpoint.
Note: Unlike most DELETE requests, the id
value must be added to the request body instead of the parameters.
Authentication
- authToken in header
Body
emailstring
The email address associated with the user's account.>= 1 charactersExample: user@example.comnamestring
The internal name assigned to the generated API token.Example: customer storefront tokenidinteger
requiredThe internal ID for the API token.Example: 123
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataarray[]
example
Get Storefront authToken with Credentials
POST https://api-b2b.bigcommerce.com/api/v3/io/auth/customersRequest
Uses the login credentials of a storefront customer or a Company user to generate a storefront authToken to validate requests to the B2B Storefront GraphQL API. Unlike the Get a Storefront API authToken endpoint, this request does not rely on a JWT from an active storefront session.
By default, the resulting storefront authToken is valid for 1 day. However, you can adjust its validity period with the beginAt
and endAt
fields in the request body.
Authentication
- authToken in header
Body
storeHashstring
requiredThe unique store hash for the BigCommerce store.>= 1 charactersExample: 1234abcdemailstring
requiredThe email address associated with the user's account.>= 1 charactersExample: user@example.compasswordstring
requiredThe password associated with the user's account.>= 1 charactersExample: MyPassword123channelIdnumber
requiredThe storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel.Example: 1000234Default: 1
namestring
requiredThe internal name assigned to the generated API token.Example: customer storefront tokenbeginAtinteger
The Unix timestamp indicating when the storefront authToken starts being valid.Example: 1721900486endAtinteger
The Unix timestamp indicating when the storefront authToken is no longer valid.Example: 1721900486
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataobject
example
Get a B2B Storefront Token
POST https://api-b2b.bigcommerce.com/api/v3/io/auth/customers/storefrontRequest
Generates a storefront authToken based on the supplied customerId
of a storefront customer or Company user. You can use Get Users to retrieve the IDs of Company users, or you can use Get All Customers to retrieve IDs for B2C customers and B2B buyers alike.
You can also use the BigCommerce Storefront GraphQL API to generate a Customer Access Token (CAT) and include it in the request, but this is not required for a successful response.
The storefront authToken obtained from this endpoint is valid for 1 day.
Authentication
- authToken in header
Body
customerIdinteger
requiredThe BigCommerce Customer ID.Example: 456channelIdnumber
The storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel.Example: 1000234Default: 1
customerAccessTokenobject
This object contains information related to the Customer Access Token (CAT) being associated with the storefront authToken.
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataobject
example
Get a Storefront API authToken
GET https://api-b2b.bigcommerce.com/api/v3/io/auth/storefrontRequest
Returns an existing storefront authToken from an existing JSON Web Token (JWT). You can obtain a JWT using a request to the Current Customer API. See Authentication for hosted storefronts for instructions.
The channelId
field is optional for stores with multiple storefronts, since the JWT is tied to a specific storefront session. Including it does enforce strict adherence of token-related activity to channel-specific rules and behaviors. However, it is not necessary at all for single-storefront stores because there is only one storefront channel.
The storefront authToken obtained from this endpoint is valid for 1 day.
Authentication
- authToken in header
Parameters
- jwtToken in query - stringrequiredThe JSON Web Token (JWT) obtained from a signed-in Company user. See Current Customer API to learn how to request a JWT.
- channelId in query - string
The storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel. In a multi-storefront environment, this parameter enforces strict adherence of token-related activity to channel-specific rules and behaviors.
Note: Inclusion of this parameter in single-storefront environments will result in unpredictable behavior.
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataobject
example
Get All Server to Server Tokens
GET https://api-b2b.bigcommerce.com/api/v3/io/backend/tokensRequest
Authentication
- authToken in header
Parameters
- limit in query with default of 10 - integerThe maximum number of results that can be in the response.
- offset in query0 - integerThe number of results that should be skipped in the response.
example
Response
Body
codeinteger
The HTTP Status code of the response.Default: 200
dataarray[object]
example
See something you can improve? Edit this file on GitHub