BigCommerce API Token API

openapi: 3.2.0
info:
  title: BigCommerce Storefront Token API Token API
  description: "Get and manage tokens used to authenticate cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql).\n\n## [API tokens](/docs/rest-authentication/tokens#create-a-token)\n\nGenerate tokens (JWT) for authenticating cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql). To [create a token](/docs/rest-authentication/tokens#create-a-token), send a `POST` request to `/stores/{{STORE_HASH}}/v3/storefront/api-token`.\n\n```http\nPOST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token\nX-Auth-Token: {{ACCESS_TOKEN}}\nContent-Type: application/json\nAccept: application/json\n\n{\n  \"channel_id\": 1,\n  \"expires_at\": 1602288000,\n  \"allowed_cors_origins\": \n    [\"https://store.example.com\"]\n  \n}\n```\n\n|Property|Type|Description|\n|-|-|-|\n|`channel_id`|int| Must be a valid channel ID on the store (required) |\n|`expires_at`|int| Unix timestamp in seconds (required). Does not support milliseconds, microseconds, or nanoseconds. |\n|`allowed_cors_origins`|array[str]| Allowed origins for cross origin requests (required) |\n\n[**Response:**](/docs/rest-authentication/tokens#create-a-token)\n\n```json\n{\n  \"token\":\"...eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9...\",\n  \"meta\": {\n    // ...\n  }\n}\n```\n\n\n\n## [Customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token)\n\nGenerate tokens that can make queries from the perspective of a particular customer in headless or server-side code using the [GraphQL Storefront API](/docs/storefront/graphql#customer-impersonation-tokens). To [create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token), send a `POST` request to `/v3/storefront/api-token-customer-impersonation`.\n\n```http\nPOST https://api.bigcommerce.com/stores/{STORE_HASH}/v3/storefront/api-token-customer-impersonation\nX-Auth-Token: {{ACCESS_TOKEN}}\nAccept: application/json\nContent-Type: application/json\n```\n\n[**Response:**](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token)\n\n```json\n{\n  \"data\":\n  {\n    \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\"\n  }\n  \"meta\": {}\n}\n```\n\nCustomer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the `X-Bc-Customer-Id` header sent with the GraphQL `POST` request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a [customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) to run a request in the context of customer ID `123`.\n\n```http\nPOST https://store.example.com/graphql\nAuthorization: Bearer {{CUSTOMER_IMPERSONATION_TOKEN}}\nX-Bc-Customer-Id: 123\n\n{\n    \"query\": \"query CustomerInformation {\\n  customer {\\n    firstName\\n    lastName\\n    email\\n  }\\n}\"\n}\n```\n\n\n> #### Warning\n> * Customer impersonation tokens should **never** be exposed publicly, for example, to JavaScript or HTML. These tokens should **not** be used for frontend requests.\n> * Unlike normal GraphQL API tokens, these tokens are sensitive and should be treated like secrets, just as you might treat an OAuth token.\n> * Attempts to run requests using these tokens from a web browser will be rejected.\n\n\n## Revoking tokens\nTo [revoke a token](/docs/rest-authentication/tokens#revoke-a-token), send a `DELETE` request to `/v3/storefront/api-token`.\n\n```http\nDELETE /stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation\nhost: api.bigcommerce.com\nx-Auth-Token: {{ACCESS_TOKEN}}\nSf-Api-Token: {{CUSTOMER_ID}}\n```\n\n## Additional information\n\n* [GraphQL API Overview](/docs/storefront/graphql)"
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: API Token
paths:
  /storefront/api-token:
    parameters:
    - $ref: '#/components/parameters/Accept'
    post:
      tags:
      - API Token
      summary: BigCommerce Create a Token
      description: 'Creates a Storefront API token.


        **Required Scopes**

        * `Manage` `Storefront API Tokens`'
      operationId: createToken
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/TokenPostSimple'
              - $ref: '#/components/schemas/TokenPostImpersonation'
        required: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token_Full'
        '401':
          description: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
          content: {}
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content: {}
        '422':
          description: Invalid JSON request body - missing or invalid data.
          content: {}
      x-codegen-request-body-name: body
    delete:
      tags:
      - API Token
      summary: BigCommerce Revoke a Token
      description: Revoke access for a Storefront API token. Only revoke compromised tokens under emergency situations. Let uncompromised short-lived tokens expire naturally, as you do not need to revoke these.
      operationId: revokeToken
      parameters:
      - name: Sf-Api-Token
        in: header
        description: An existing JWT token that you want to revoke.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A storefront API token revocation has been scheduled.
          content: {}
        '401':
          description: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
          content: {}
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content: {}
        '422':
          description: Invalid JWT Token provided or missing JWT token header
          content: {}
components:
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
  schemas:
    TokenPostSimple:
      type: object
      properties:
        allowed_cors_origins:
          maxItems: 1
          minItems: 1
          type: array
          description: List of allowed domains for Cross-Origin Request Sharing. Currently only accepts a single element.
          items:
            maxLength: 1
            minLength: 1
            pattern: /^https?:\/\/(?=.{1,254}(?::|$))(?:(?!\d|-)(?![a-z0-9\-]{1,62}-(?:\.|:|$))[a-z0-9\-]{1,63}\b(?!\.$)\.?)+(:\d+)?$/i;
            type: string
      x-internal: false
      x-examples:
        example-1:
          allowed_cors_origins:
          - https://www.yourstorefront.com/
    Token_Base:
      type: object
      properties:
        token:
          type: string
          description: JWT Token for accessing the Storefront API
      x-internal: false
    Token_Full:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Token_Base'
        meta:
          type: object
          properties: {}
          additionalProperties: true
          description: Response metadata.
    TokenPostImpersonation:
      type: object
      x-internal: false
      x-examples: {}
      properties:
        channel_id:
          type: integer
          minimum: 1
          description: Channel ID for requested token
          example: 1
        expires_at:
          type: integer
          description: Unix timestamp (UTC time) defining when the token should expire. Supports seconds, but does not support milliseconds, microseconds, or nanoseconds.
          example: 1885635176
          minimum: 0
      required:
      - channel_id
      - expires_at
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        | Storefront API Customer Impersonation Tokens | manage | `store_storefront_api_customer_impersonation` |

        | Storefront API Tokens | manage | `store_storefront_api` |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      name: X-Auth-Token
      in: header