> ## 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 Admin API using OAuth 2.0.

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

## Prerequisites

Register your application 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 back-office tools, CRM sync jobs, reporting pipelines, and migration scripts. Request an access token directly from the token endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://firespark.cloud/api/admin/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=customers:read customers:write orders:read"
  ```
</RequestExample>

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

### Token request parameters

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

## Use the access token

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

```bash theme={null}
curl "https://firespark.cloud/api/admin/v1/customers/bulk?from=0&to=100" \
  -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 admin-api/openapi.json POST /oauth/token
openapi: 3.0.1
info:
  title: Fire spark Admin API
  description: Back-office and merchant operations endpoints for Fire spark.
  version: 1.0.0
servers:
  - url: https://firespark.cloud/api/admin/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: 0c5c7abb-0542-407b-8f0a-9b405c9057f6
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````