Create token

POST/api/v1/tokens

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.

Operation ID: create_token·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: APITokenCreate

namestringrequired: Token name
descriptionstring: Optional description
expires_in_daysinteger: Expiration in days (1-365, default: 365)
business_idsarray · 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.
scopesarray · 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_ipsarray · string: When set, this token is refused (403 AUTH_028) unless the request comes from one of these IPv4/IPv6 addresses or CIDR ranges, or from a named cloud preset: preset:google (Google services, where Apps Script and Google Sheets call from) or preset:aws:<region> (Amazon EC2 in that region). Presets are shared by every customer of that cloud, so they are much weaker than your own addresses. Omit or leave empty to allow any IP. Set at minting; mint a new token to change the list.
rate_limit_per_minuteinteger: 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.

Responses

201Successful Response

Schema: SuccessEnvelope_APITokenCreateResponse_

successboolean
messagestring
codestring
dataAPITokenCreateResponse

400Bad Request - Invalid input

Schema: ErrorResponse

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

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

Schema: ErrorResponse

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

403Forbidden - Insufficient permissions

Schema: ErrorResponse

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

422Validation Error

Schema: ErrorResponse

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

Code samples

POST/api/v1/tokens

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"
  ]
}'