POST /api/v1/businesses/{id}/api-keys

POST/api/v1/businesses/{id}/api-keys

Omitted scopes grant no permissions. Token is hashed server-side; never returned by subsequent list calls. Integration permission: integrations.manage. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with integrations.manage.

Parameters

Parameter	In	Type	Description
`id`Required	path	`string`	Authorized business context. Never inferred from client record IDs.Format: uuid

Request

Field	Type	Description & constraints
`name`Required	`string`	Human-readable name shown in the workspace.
`scopes`	`array<orders.read \| orders.write \| resources.read \| resources.write \| settings.read \| settings.write \| accounts.manage \| planning.read \| planning.run \| planning.edit \| planning.publish \| availability.query \| reservations.confirm \| evidence.read \| evidence.manage \| integrations.manage \| scenarios.read \| scenarios.write>`	Explicit operation permissions granted to this API key.

Example JSON body

{
  "name": "Example Services",
  "scopes": [
    "orders.read",
    "orders.write"
  ]
}

Request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "scopes": {
      "type": "array",
      "items": {
        "enum": [
          "orders.read",
          "orders.write",
          "resources.read",
          "resources.write",
          "settings.read",
          "settings.write",
          "accounts.manage",
          "planning.read",
          "planning.run",
          "planning.edit",
          "planning.publish",
          "availability.query",
          "reservations.confirm",
          "evidence.read",
          "evidence.manage",
          "integrations.manage",
          "scenarios.read",
          "scenarios.write"
        ]
      }
    }
  },
  "required": [
    "name"
  ]
}

Example request

Replace synthetic identifiers and credentials. Example dates, coordinates, revisions, and IDs are not production defaults. Read the workflow guide before making a write.

curl --request POST 'https://route-api.okok.space/api/v1/businesses/11111111-1111-4111-8111-111111111111/api-keys' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Example Services","scopes":["orders.read","orders.write"]}'

Responses

Examples illustrate the documented shape; optional fields and current state can differ. JSON extraction/body-limit errors may be plain text.

200 · Successful response

application/json

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`	`string`	Human-readable name shown in the workspace.
`token`	`string`	Private bearer/challenge token returned by the appropriate authentication flow.
`scopes`	`array<string>`	Explicit operation permissions granted to this API key.

Illustrative response

{
  "id": "example-id",
  "name": "Example Services",
  "token": "REPLACE_WITH_TOKEN",
  "scopes": [
    "orders.read",
    "orders.write"
  ]
}

Response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "token": {
      "type": "string"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

401 · Missing/invalid/revoked token

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing/invalid/revoked token"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

403 · Business membership or required API-key scope denied

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Business membership or required API-key scope denied"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

404 · Record not found in authorized business

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "not_found",
    "message": "Record not found in authorized business"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "conflict",
    "message": "Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

422 · Domain validation rejected the operation

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "validation",
    "message": "Domain validation rejected the operation"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

503 · Required persistence, map/routing or other infrastructure unavailable

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unavailable",
    "message": "Required persistence, map/routing or other infrastructure unavailable"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

← All endpoints Integration workflows →

Create key; secret returned once

Authentication

Parameters

Request

Example JSON body

Example request

Responses

200 · Successful response

401 · Missing/invalid/revoked token

403 · Business membership or required API-key scope denied

404 · Record not found in authorized business

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

422 · Domain validation rejected the operation

503 · Required persistence, map/routing or other infrastructure unavailable