openapi: 3.1.0
info:
  title: 'Admin Authentication: Storefront API Tokens'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/storefront/api-token:
    post:
      operationId: createToken
      summary: Create a Token
      description: >-
        Creates a Storefront API token. This endpoint creates storefront tokens that support CORS via
        `allowed_cors_origins` and are intended for browser-based applications.


        For server-to-server integrations, you must use the [private token endpoint](#operation/createPrivateToken)
        instead.


        **Required Scopes**

        * `Manage` `Storefront API Tokens`


        > NOTE: While neither `channel_id` nor `channel_ids` is labelled as required, one must be included in the
        request body. Including neither will throw an error, and including both will result in unexpected behaviors.
      tags:
        - apiToken
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token_Full'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                allowed_cors_origins:
                  type: array
                  items:
                    type: string
                  description: >-
                    List of allowed domains for Cross-Origin Request Sharing. Currently accepts a maximum of two domains
                    per created token.
                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.
                channel_ids:
                  type: array
                  items:
                    type: integer
                  description: >-
                    A list of channel IDs that are valid for the requested token. Use this field for one or more channel
                    IDs. One of `channel_id` or `channel_ids` is required; including neither returns an error, and
                    including both results in unexpected behavior.
                channel_id:
                  type: integer
                  description: >-
                    Channel ID that is valid for the requested token. Use this field to enter a single channel ID. We
                    support this field for backwards compatibility, but `channel_ids` is preferred. One of `channel_id`
                    or `channel_ids` is required; including neither returns an error, and including both results in
                    unexpected behavior.
              required:
                - expires_at
    delete:
      operationId: revokeToken
      summary: Revoke a Token
      description: >-
        Revoke access for a storefront API token or a private API token. Only revoke compromised tokens under emergency
        situations. Let uncompromised short-lived tokens expire naturally, as you do not need to revoke these.
      tags:
        - apiToken
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
        - 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 or private API token revocation has been scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API Token_revokeToken_Response_200'
  /stores/{store_hash}/v3/storefront/api-token-customer-impersonation:
    post:
      operationId: createTokenWithCustomerImpersonation
      summary: Create a Token
      description: >-
        Returns a Storefront API token that allows your application to impersonate customers when making GraphQL `POST`
        requests. For more information on how to use the returned token, see [customer impersonation
        tokens](/developer/docs/storefront/guides/graphql-storefront-api/authentication#customer-impersonation-tokens).


        **Required Scopes**

        * `Manage` `Storefront API Customer Impersonation Tokens`


        > NOTE: While neither `channel_id` nor `channel_ids` is labelled as required, one must be included in the
        request body. Including neither will throw an error, and including both will result in unexpected behaviors.
      tags:
        - customerImpersonationToken
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token_Full'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPostImpersonation'
  /stores/{store_hash}/v3/storefront/api-token-private:
    post:
      operationId: createPrivateToken
      summary: Create a Private API Token
      description: >-
        Creates a private token for server-to-server integrations. Private tokens are always stateless (no session
        required) and provide better performance for server-to-server use cases. The API will reject private
        token-authenticated requests that originate from web browsers.


        **Required Scopes**

        * `Manage` `Storefront API Tokens`


        > NOTE: While neither `channel_id` nor `channel_ids` is labelled as required, one must be included in the
        request body. Including neither will throw an error, and including both will result in unexpected behaviors.
      tags:
        - privateApiToken
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token_Full'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPostPrivate'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    Token_Base:
      type: object
      properties:
        token:
          type: string
          description: JWT Token for accessing the Storefront API
      title: Token_Base
    TokenFullMeta:
      type: object
      properties: {}
      description: Response metadata.
      title: TokenFullMeta
    Token_Full:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Token_Base'
        meta:
          $ref: '#/components/schemas/TokenFullMeta'
          description: Response metadata.
      title: Token_Full
    API Token_revokeToken_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: API Token_revokeToken_Response_200
    TokenPostImpersonation:
      type: object
      properties:
        channel_ids:
          type: array
          items:
            type: integer
          description: >-
            A list of channel IDs that are valid for the requested token. Use this field for one or more channel IDs.
            One of `channel_id` or `channel_ids` is required; including neither returns an error, and including both
            results in unexpected behavior.
        channel_id:
          type: integer
          description: >-
            Channel ID that is valid for the requested token. Use this field to enter a single channel ID. We support
            this field for backwards compatibility, but `channel_ids` is preferred. One of `channel_id` or `channel_ids`
            is required; including neither returns an error, and including both results in unexpected behavior.
        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.
      required:
        - expires_at
      title: TokenPostImpersonation
    TokenPostPrivateScopesItems:
      type: string
      enum:
        - Unauthenticated
        - Customer
        - B2B
      title: TokenPostPrivateScopesItems
    TokenPostPrivate:
      type: object
      properties:
        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.
        channel_ids:
          type: array
          items:
            type: integer
          description: >-
            A list of channel IDs that are valid for the requested token. Use this field for one or more channel IDs.
            One of `channel_id` or `channel_ids` is required; including neither returns an error, and including both
            results in unexpected behavior.
        channel_id:
          type: integer
          description: >-
            Channel ID that is valid for the requested token. Use this field to enter a single channel ID. We support
            this field for backwards compatibility, but `channel_ids` is preferred. One of `channel_id` or `channel_ids`
            is required; including neither returns an error, and including both results in unexpected behavior.
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/TokenPostPrivateScopesItems'
          description: >-
            Access scope identifiers. Required for private tokens. Include all scopes required by the GraphQL fields you
            need.
      required:
        - expires_at
        - scopes
      title: TokenPostPrivate
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      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](/developer/docs/overview/api-fundamentals/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts).


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