API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Authorization

Per-entity ability probe endpoint.

The UI calls POST /api/auth/can to ask "given the user's current scopes

  • AND the entity's current state, would these actions be allowed?" — BEFORE firing the actual command.

The response is a flat map keyed by the requested scope. Each entry has:

  • allowed (bool) — combined verdict (scope held AND state allows)
  • reason (string) — present on denials, suitable for tooltip display

Backend always remains authoritative via the bus AuthorizationStage; this endpoint is advisory and intended purely to drive UI gating.

Probe per-entity abilities

Returns a map of scope → verdict for the current user against an optional subject entity. Both the user-holds-scope check and the entity-state check must pass for allowed to be true.

Authorizations:
Bearer
Request Body schema: application/json
required

Subject URI (optional) and a list of scopes to probe

subject
string

ResourceUri of the entity being probed. Omit for scope-only checks.

scopes
required
Array of strings [ 1 .. 50 ] items

Responses

Request samples

Content type
application/json
{
  • "subject": "glacia:///document/documents/01KT0000000000000000000000",
  • "scopes": [
    ]
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Authentication

Authentication API Resource.

Delete account (GDPR right to erasure)

Permanently anonymizes the authenticated user account. All PII is removed. This action is irreversible.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

User login

Authenticate a user with email and password. Returns access and refresh tokens.

Request Body schema: application/json
required

Login credentials

email
required
string <email>

User email address

password
required
string <password>

User password

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "your-password"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

User logout

Invalidate the current session.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Logout from all devices

Revoke all active sessions for the authenticated identity.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Logout from other devices

Revoke all active sessions for the authenticated identity except the current one.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Refresh access token

Use a refresh token to obtain a new access token.

Request Body schema: application/json
required

Refresh token

refreshToken
required
string

The refresh token

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Self-serve registration

Create a new account with email and password. No tokens are returned — a verification email is sent and the user must verify, then log in.

Request Body schema: application/json
required

Registration details

email
required
string <email>

User email address

password
required
string <password>

Password (minimum 8 characters)

firstName
required
string

First name

company
string

Company / organization name (optional; used for the first-organization step after verification)

country
string

Country (optional)

marketingOptIn
boolean
Default: false

Consent to marketing communications

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "your-secure-password",
  • "firstName": "Alex",
  • "company": "string",
  • "country": "string",
  • "marketingOptIn": false
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Request password reset

Request a password reset email. Always returns success to avoid leaking email existence.

Request Body schema: application/json
required

Email address

email
required
string <email>

The email address associated with the account

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Resend email verification

Request a new verification email. Always returns success to avoid leaking email existence.

Request Body schema: application/json
required

Email address

email
required
string <email>

Email address to resend verification to

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Reset password

Submit the token received by email along with a new password to complete the password reset.

Request Body schema: application/json
required

Reset token and new password

token
required
string

The password reset token received by email

newPassword
required
string <password>

The new password (minimum 8 characters)

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "newPassword": "pa$$word"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Select tenant

Validates membership and issues a tenant-scoped access token. Include this token as Bearer in subsequent requests to operate within the selected tenant.

Authorizations:
Bearer
Request Body schema: application/json
required

Tenant selection

tenantId
required
string

ULID of the tenant to operate under

Responses

Request samples

Content type
application/json
{
  • "tenantId": "01HQWXYZ1234567890TENANT"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Verify email address

Submit the token received by email to verify the email address. No authentication required.

Request Body schema: application/json
required

Verification token

token
required
string

The verification token received by email

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

IAM / External identity

Social-signup / SSO entry-point endpoints.

POST /api/iam/auth/external/{kind}/start Mints a signed HMAC state token and returns the provider's authorization URL the browser must navigate to (or feed into a client-side SDK such as Apple's AppleID.auth.init). Same JSON contract as StorageOAuthResource on the Storage module.

The callback half of the flow lives on a separate invokable Symfony route ({@see \Glacia\IAM\Infrastructure\Api\ApiPlatform\State\Provider\ExternalIdentityCallbackProvider}) because the OAuth callback returns a redirect (with the freshly-issued tokens in the URL fragment) — that response shape does not fit API Platform's resource serialization.

Public route (no auth required) — see iam/prepend/security.yaml.

Begin an external-identity (social / SSO) authentication flow

Mints an HMAC-signed state token and returns the provider authorization URL the browser must navigate to. The same JSON shape is consumed by client-side SDK flows (e.g. Apple JS SDK).

Authorizations:
Bearer
path Parameters
kind
required
string
Enum: "google_oauth" "facebook_oauth" "apple_oauth" "oidc" "saml"

Provider discriminator

Request Body schema: application/json
optional

Optional return URI overriding the platform default.

returnUri
string or null

Final user-facing URL to bounce to after the callback succeeds. Must match the configured allow-list when one is set.

Responses

Request samples

Content type
application/json
{
  • "returnUri": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "kind": "string",
  • "authorizationUrl": "string",
  • "state": "string",
  • "redirectUri": "string",
  • "returnUri": "string",
  • "expiresInSeconds": 0
}