# Collections access token

Exchange your merchant **API key** (`client_id`) and **API secret** (`client_secret`) from the dashboard for a short-lived Bearer token with scope **collections**. The same credential pair works on the disbursements token endpoint. Use this token only for `POST /v1/collect` and collection status GET.

## Headers

```http
Content-Type: application/json
```

Token body fields: [Field reference](https://docs.swarmbyte.com/field-reference.md) → OAuth token.

## Body

```json
{
  "grant_type": "client_credentials",
  "client_id": "<merchant_api_key>",
  "client_secret": "<merchant_api_secret>"
}
```

Only `grant_type` value `client_credentials` is supported; otherwise **400** `Unsupported grant_type`.

## Responses

- **200** — JSON with `access_token`, `token_type: "bearer"`, `expires_in` (seconds; typically 180).
- **401** — Invalid credentials or merchant not eligible (pending approval, KYC, disabled, view-only, suspended).
- **403** — IP allowlist blocks access before a token is issued.
- **429** — Rate limit (token routes are throttled per IP).
- **503** — Service temporarily unavailable; retry later.

## HTTP status codes (API reference)

| HTTP | When |
| --- | --- |
| **200** | Success: `access_token`, `token_type: "bearer"`, `expires_in` (seconds). |
| **400** | Invalid request body — e.g. unsupported `grant_type` (`Unsupported grant_type`), or missing/invalid `client_id` / `client_secret`. |
| **401** | `Missing API credentials`; `Invalid API credentials`; merchant not eligible: `Your merchant account is pending approval`; `Your account is not verified. Please complete KYC.`; `Your account has been disabled.`; `Your account is in view-only mode. API mutations are disabled.`; `This merchant account has been suspended.` |
| **403** | Request IP is not on your programmatic allowlist (configure in the dashboard). Response may include `clientIp`. |
| **429** | Too many token requests — back off and retry. |
| **503** | `Token service temporarily unavailable` — retry later. |

## Example request

```bash
curl -sS -X POST 'https://core.swarmbyte.com/v1/oauth/collections/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_API_KEY",
    "client_secret": "YOUR_API_SECRET"
  }'
```

## Example response (200)

```json
{
  "access_token": "<opaque_token>",
  "token_type": "bearer",
  "expires_in": 180
}
```

Source: https://docs.swarmbyte.com/oauth-collections-token