# API Tokens — DayZero API

> Create, list, and revoke Bearer API tokens.

7 endpoints. OpenAPI for just this tag: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json · HTML: https://www.ondayzero.com/docs/reference/api-tokens · All tags: https://www.ondayzero.com/docs/reference/index.md

## Endpoints

- `GET /api/v1/tokens` — List tokens
- `POST /api/v1/tokens` — Create token
- `GET /api/v1/tokens/access` — Get API access status
- `POST /api/v1/tokens/access-request` — Request API access
- `DELETE /api/v1/tokens/{token_id}` — Delete token
- `POST /api/v1/tokens/{token_id}/revoke` — Revoke token
- `POST /api/v1/tokens/{token_id}/rotate` — Rotate token

---

## GET /api/v1/tokens

> List tokens

- **Tag:** api-tokens
- **Operation ID:** `list_tokens`

### Description

List all API tokens for current user

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Parameters

- `include_revoked` (query, boolean, optional) — Include revoked tokens
- `cursor` (query, string, optional) — Cursor for pagination
- `limit` (query, integer, optional) — Pagination limit
- `direction` (query, string, optional) — Pagination direction: 'next' or 'prev'
- `include_total_count` (query, boolean, optional) — Whether to include total count (expensive - avoid if possible)
- `sort_by` (query, string, optional) — Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.
- `descending` (query, boolean, optional) — Sort direction: true for descending (newest/largest first), false for ascending

### Responses

#### 200 — Successful Response

Schema: `SuccessEnvelope_APITokenListResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (APITokenListResponse)

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X GET 'https://api.ondayzero.com/api/v1/tokens' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID'
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
  },
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

response = httpx.get("https://api.ondayzero.com/api/v1/tokens", headers=headers)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/list-tokens
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/list-tokens/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## POST /api/v1/tokens

> Create token

- **Tag:** api-tokens
- **Operation ID:** `create_token`

### Description

Create a new API token. Requires two-factor authentication on the account and a recent verification of both factors in the current session; must be called from the DayZero web app, not with an API token.

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Request body

Schema: `APITokenCreate`

- `name` (string · required) — Token name
- `description` (string) — Optional description
- `expires_in_days` (integer) — Expiration in days (1-365, default: 365)
- `business_ids` (array · string) — Limit the token to these businesses (UUIDs you can access). Omit for every business you can reach. A limited token gets 403 `AUTH_070` on any other business, and cannot elevate around it.
- `scopes` (array · string) — Token surface. Omit for full access. `read_only` blocks every mutating endpoint. `credit` limits the token to the partner-credit API; `credit:read` to its GET endpoints; `credit:payments` to POST /api/v1/credit/payments and its settlement/reversal paths, plus GET on a line's payoff-quote and payments.
- `allowed_ips` (array · string) — When set, this token is refused (403 AUTH_028) unless the request comes from one of these IPv4/IPv6 addresses or CIDR ranges. Omit or leave empty to allow any IP. Set at minting; mint a new token to change the list.
- `rate_limit_per_minute` (integer) — Requests per minute this token may make (sliding window). Omit for the platform default. Over budget the API answers 429 AUTH_058 and the token's owner is alerted.

### Example request

```json
{
  "allowed_ips": [
    "203.0.113.10",
    "198.51.100.0/24"
  ],
  "description": "Read-only token for the reporting assistant",
  "expires_in_days": 90,
  "name": "Month-end close agent",
  "scopes": [
    "read_only"
  ]
}
```

### Responses

#### 201 — Successful Response

Schema: `SuccessEnvelope_APITokenCreateResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (APITokenCreateResponse)

#### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X POST 'https://api.ondayzero.com/api/v1/tokens' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "allowed_ips": [
    "203.0.113.10",
    "198.51.100.0/24"
  ],
  "description": "Read-only token for the reporting assistant",
  "expires_in_days": 90,
  "name": "Month-end close agent",
  "scopes": [
    "read_only"
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "allowed_ips": [
    "203.0.113.10",
    "198.51.100.0/24"
  ],
  "description": "Read-only token for the reporting assistant",
  "expires_in_days": 90,
  "name": "Month-end close agent",
  "scopes": [
    "read_only"
  ]
}),
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {'allowed_ips': ['203.0.113.10', '198.51.100.0/24'],
 'description': 'Read-only token for the reporting assistant',
 'expires_in_days': 90,
 'name': 'Month-end close agent',
 'scopes': ['read_only']}

response = httpx.post("https://api.ondayzero.com/api/v1/tokens", headers=headers, json=payload)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/create-token
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/create-token/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## GET /api/v1/tokens/access

> Get API access status

- **Tag:** api-tokens
- **Operation ID:** `get_api_access`

### Description

Whether the caller may create and use API tokens. API access is off until a DayZero operator approves a request for it.

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Responses

#### 200 — Successful Response

Schema: `SuccessEnvelope_ApiAccessStateResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (ApiAccessStateResponse)

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X GET 'https://api.ondayzero.com/api/v1/tokens/access' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID'
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens/access', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
  },
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

response = httpx.get("https://api.ondayzero.com/api/v1/tokens/access", headers=headers)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/get-api-access
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/get-api-access/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## POST /api/v1/tokens/access-request

> Request API access

- **Tag:** api-tokens
- **Operation ID:** `request_api_access`

### Description

Ask DayZero for API access. Every request is reviewed by a DayZero operator; the caller is emailed when it is approved or denied.

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Request body

Schema: `ApiAccessRequestCreate`

- `use_case` (string · required) — What you are building and which data it needs. A DayZero operator reads this to decide the request.
- `company_name` (string) — Company or product the integration is for

### Example request

```json
{
  "company_name": "Northwind Advisory",
  "use_case": "Nightly sync of paid invoices from DayZero into our data warehouse, read-only, from a single server."
}
```

### Responses

#### 201 — Successful Response

Schema: `SuccessEnvelope_ApiAccessStateResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (ApiAccessStateResponse)

#### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 409 — Conflict - Resource already exists or is in an incompatible state

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 429 — Too Many Requests - Rate limit exceeded; back off and retry

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X POST 'https://api.ondayzero.com/api/v1/tokens/access-request' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "company_name": "Northwind Advisory",
  "use_case": "Nightly sync of paid invoices from DayZero into our data warehouse, read-only, from a single server."
}'
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens/access-request', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "company_name": "Northwind Advisory",
  "use_case": "Nightly sync of paid invoices from DayZero into our data warehouse, read-only, from a single server."
}),
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {'company_name': 'Northwind Advisory',
 'use_case': 'Nightly sync of paid invoices from DayZero into our data '
             'warehouse, read-only, from a single server.'}

response = httpx.post("https://api.ondayzero.com/api/v1/tokens/access-request", headers=headers, json=payload)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/request-api-access
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/request-api-access/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## DELETE /api/v1/tokens/{token_id}

> Delete token

- **Tag:** api-tokens
- **Operation ID:** `delete_token`

### Description

Permanently delete an API token

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Parameters

- `token_id` (path, string, required)

### Responses

#### 200 — Successful Response

Schema: `app__core__success__MessageResponse`

- `success` (boolean)
- `message` (string)
- `code` (string)

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 404 — Not Found - Resource does not exist

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X DELETE 'https://api.ondayzero.com/api/v1/tokens/{token_id}' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID'
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens/{token_id}', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
  },
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

response = httpx.delete("https://api.ondayzero.com/api/v1/tokens/{token_id}", headers=headers)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/delete-token
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/delete-token/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## POST /api/v1/tokens/{token_id}/revoke

> Revoke token

- **Tag:** api-tokens
- **Operation ID:** `revoke_token`

### Description

Revoke an API token.

**Path Parameters:**
- `token_id`: UUID of the token to revoke

**Request Body:** (optional)
- `reason`: Optional reason for revocation

**Note:** Once revoked, the token can no longer be used for authentication.
The token is added to a blacklist and will be rejected on all future requests.

Revoked tokens cannot be un-revoked.

**Returns:** Revoked token information with revocation timestamp.

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Parameters

- `token_id` (path, string, required)

### Responses

#### 201 — Successful Response

Schema: `SuccessEnvelope_APITokenRevokeResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (APITokenRevokeResponse)

#### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 404 — Not Found - Resource does not exist

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X POST 'https://api.ondayzero.com/api/v1/tokens/{token_id}/revoke' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d ''
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens/{token_id}/revoke', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {}

response = httpx.post("https://api.ondayzero.com/api/v1/tokens/{token_id}/revoke", headers=headers, json=payload)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/revoke-token
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/revoke-token/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

## POST /api/v1/tokens/{token_id}/rotate

> Rotate token

- **Tag:** api-tokens
- **Operation ID:** `rotate_token`

### Description

Mint a replacement for an API token and keep the old one working for an overlap window, so credentials can be swapped without downtime. Same two-factor step-up as creating a token.

### Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

### Parameters

- `token_id` (path, string, required)

### Responses

#### 201 — Successful Response

Schema: `SuccessEnvelope_APITokenRotateResponse_`

- `success` (boolean)
- `message` (string)
- `code` (string)
- `data` (APITokenRotateResponse)

#### 400 — Bad Request - Invalid input

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 401 — Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 403 — Forbidden - Insufficient permissions

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 404 — Not Found - Resource does not exist

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

#### 422 — Validation Error

Schema: `ErrorResponse`

- `error` (string · required) — Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`.
- `message` (string · required) — Human-readable explanation, safe to show to end users.
- `code` (string · required) — Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`).
- `request_id` (string) — Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied.
- `errors` (object) — Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

### Code samples

#### cURL

```bash
curl -X POST 'https://api.ondayzero.com/api/v1/tokens/{token_id}/rotate' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d ''
```

#### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/tokens/{token_id}/rotate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await response.json();
```

#### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {}

response = httpx.post("https://api.ondayzero.com/api/v1/tokens/{token_id}/rotate", headers=headers, json=payload)
data = response.json()
```

### See also

- HTML version: https://www.ondayzero.com/docs/reference/api-tokens/rotate-token
- OpenAPI slice: https://www.ondayzero.com/docs/reference/api-tokens/rotate-token/openapi.json
- Other endpoints in **api-tokens**: https://www.ondayzero.com/docs/reference/api-tokens (markdown bundle: https://www.ondayzero.com/docs/reference/api-tokens.md, OpenAPI: https://www.ondayzero.com/docs/reference/api-tokens/openapi.json)
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md