Authentication

Every request to /api/v1/* must include an Authorization: Bearer <api-key> header. Keys are issued by company admins through the locco web app.

Bearer token model

locco uses opaque bearer tokens. The server hashes the key at rest, so the plaintext value is only visible to the caller once (at creation time). There is no way to recover a lost key. Rotate instead.

Issue a key under Settings → Integrations → API Keys in the locco web app. The “API documentation” button on that page links here.

Key format

Keys are strings of the shape:

locco_live_<opaque-random-string>

The locco_live_ prefix is stable. Treat the key as a secret: store it in your secret manager, never commit it to version control, and never log it. The key grants access to every endpoint the issuing user has permission for in the target company.

The X-Company-Id header

Every API-key request MUST include the target company’s Guid in the X-Company-Id header:

X-Company-Id: 00000000-0000-0000-0000-000000000000

A missing header returns HTTP 400 with code: "VALIDATION_FAILED". The header is required on every request, even when the key’s owning user belongs to only one company. locco never infers the target tenant from the key alone.

Find the company Guid in the locco web app URL when you are in the target company, or request it from your account owner.

Example request

bash
curl https://api.locco.hr/api/v1/travel-entries \
  -H "Authorization: Bearer locco_live_..." \
  -H "X-Company-Id: 00000000-0000-0000-0000-000000000000"

Successful responses carry rate-limit headers (see Rate limits) and a standard JSON body. Error responses carry a stable machine-readable code (see Errors).

Key rotation

To rotate a key without downtime:

  1. Generate a new key in the settings page. Copy the plaintext value into your secret manager immediately.
  2. Deploy your clients with the new key in parallel with the old one.
  3. Once traffic has shifted, revoke the old key. Revoked keys return HTTP 401.

There is no “regenerate” operation that preserves the old key value. Always issue a new key, migrate, then revoke the old one.

Entitlement

The target company must have the ApiAccess subscription feature, which is included with the Enterprise plan and available as a paid add-on on every other tier. Requests to a company without the feature return HTTP 402 with code: "API_ACCESS_NOT_ENABLED". See Pricing and entitlement for the full per-tier matrix and the response shape.

See the error catalog for the full list of machine-readable error codes and the appropriate partner response for each one.