POST /api/v1/driver/login

POST/api/v1/driver/login

Separate driver identity; administrator session cannot perform driver work. Business-specific access/activation; no public driver registration. Rate limited. If business_id omitted, backend resolves authorized driver identity/business choices.

Authentication

No bearer token required. This does not remove validation or rate limits.

Parameters

No path or query parameters.

Request

Field	Type	Description & constraints
`email`Required	`string`	Account email address.Format: email
`password`Required	`string`	Private chosen password; never expose it in client bundles or logs.
`business_id`	`string`	Resource-specific value; see the related workflow and schema.Format: uuid

Example JSON body

{
  "email": "dispatcher@example.com",
  "password": "Example-passphrase-42!",
  "business_id": "11111111-1111-4111-8111-111111111111"
}

Request schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string"
    },
    "business_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "email",
    "password"
  ]
}

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/driver/login' \
  --header 'Content-Type: application/json' \
  --data '{"email":"dispatcher@example.com","password":"Example-passphrase-42!","business_id":"11111111-1111-4111-8111-111111111111"}'

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
`token`Required	`string`	Opaque driver bearer token. Keep private.
`business_id`Required	`string`	Resource-specific value; see the related workflow and schema.Format: uuid
`driver`Required	`object`	Resource-specific value; see the related workflow and schema.
`expires_at`	`string`	Latest instant this temporary offer or session remains valid.Format: date-time

driver fields

Field	Type	Description & constraints
`driver.id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`driver.name`Required	`string`	Human-readable name shown in the workspace.
`driver.email`Required	`string`	Account email address.Format: email
`driver.active`	`boolean`	Whether this account or integration is enabled.
`driver.duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`driver.location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`driver.duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`driver.activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

Field	Type	Description & constraints
`requires_business_selection`Required	`true`	Resource-specific value; see the related workflow and schema.
`businesses`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`reauthenticate_on_selection`Required	`true`	Resource-specific value; see the related workflow and schema.

businesses[] fields

Field	Type	Description & constraints
`businesses.business_id`Required	`string`	Resource-specific value; see the related workflow and schema.Format: uuid
`businesses.name`Required	`string`	Human-readable name shown in the workspace.

Illustrative response

{
  "token": "REPLACE_WITH_TOKEN",
  "business_id": "11111111-1111-4111-8111-111111111111",
  "driver": {
    "id": "example-id",
    "name": "Example Services",
    "email": "dispatcher@example.com",
    "active": true,
    "duty_status": "online",
    "location": {
      "latitude": 52.2297,
      "longitude": 21.0122
    },
    "duty_started_at": "2026-11-02T09:00:00Z",
    "activation_code": "example"
  },
  "expires_at": "2026-11-02T09:00:00Z"
}

Response schema

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/DriverSessionResponse"
    },
    {
      "$ref": "#/components/schemas/DriverBusinessChoices"
    }
  ]
}

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 →

Driver login

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