> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Token

> Authenticate with the Integrations API using OAuth 2.0.

The Integrations API uses [OAuth 2.0](https://oauth.net/2/) (RFC 6749) with the **client credentials** grant for server-to-server authentication.

## Prerequisites

Register your integration in the [Fire spark dashboard](https://firespark.cloud) to obtain a `client_id` and `client_secret`. Store the client secret on your server only.

## Client credentials grant

Use this grant for machine-to-machine integrations such as POS, RMS, and aggregator connectors. Request an access token directly from the token endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://firespark.cloud/api/integrations/v1/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "client_secret=YOUR_CLIENT_SECRET" \
    -d "scope=menus:write stores:read orders:read"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "menus:write stores:read orders:read"
  }
  ```
</ResponseExample>

### Token request parameters

| Parameter       | Required | Description                                                                             |
| --------------- | -------- | --------------------------------------------------------------------------------------- |
| `grant_type`    | Yes      | Must be `client_credentials`.                                                           |
| `client_id`     | Yes      | Your integration client ID.                                                             |
| `client_secret` | Yes      | Your integration client secret.                                                         |
| `scope`         | No       | Space-delimited list of scopes. Defaults to the scopes configured for your integration. |

### Available scopes

| Scope               | Access                               |
| ------------------- | ------------------------------------ |
| `menus:read`        | Read menus, categories, and products |
| `menus:write`       | Create and update menus              |
| `stores:read`       | Read store configuration             |
| `stores:write`      | Update store configuration           |
| `channels:read`     | Read sales channels                  |
| `channels:write`    | Update sales channels                |
| `brands:read`       | Read brands                          |
| `orders:read`       | Read orders                          |
| `orders:write`      | Create and update orders             |
| `fulfillment:read`  | Read fulfillment options             |
| `fulfillment:write` | Update fulfillment options           |

## Use the access token

Include the access token in the `Authorization` header of every authenticated request.

```bash theme={null}
curl "https://firespark.cloud/api/integrations/v1/menus?store_id=downtown&channel_id=app" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

<Warning>
  Access tokens expire after the number of seconds indicated by `expires_in`.
  Request a new token before expiry. Do not expose client secrets or access
  tokens in client-side code.
</Warning>

## Error responses

Token and authorization errors follow RFC 6749. The token endpoint returns `application/json` with an `error` field.

| Error                    | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| `invalid_request`        | A required parameter is missing or malformed.              |
| `invalid_client`         | Client authentication failed.                              |
| `invalid_grant`          | The provided credentials are invalid.                      |
| `unauthorized_client`    | The client is not authorized for this grant type.          |
| `unsupported_grant_type` | The `grant_type` value is not supported.                   |
| `invalid_scope`          | The requested scope is invalid or exceeds what is allowed. |

```json Error theme={null}
{
  "error": "invalid_client",
  "details": "Client authentication failed."
}
```


## OpenAPI

````yaml integrations-api/openapi.json POST /oauth/token
openapi: 3.0.1
info:
  title: Fire spark Integrations API
  description: POS and RMS integration endpoints for Fire spark.
  version: 1.0.0
servers:
  - url: https://firespark.cloud/api/integrations/v1
security:
  - bearerAuth: []
paths:
  /oauth/token:
    post:
      summary: Token
      description: Obtain an access token using the OAuth 2.0 client credentials grant.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                client_id:
                  type: string
                client_secret:
                  type: string
                scope:
                  type: string
                  description: >-
                    Space-delimited scopes such as menus:write stores:read
                    orders:read.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TokenResponse'
      security: []
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````