Client API Keys

Kartorium client API keys let trusted organization members access client-facing backend data without using a browser session. Keys are scoped to one Auth0 organization and are managed by Kartorium super admins from /admin/org-settings.

Delivery Flow

1. A Kartorium super admin selects an organization, recipient member, label, expiration date, and allowed scopes.
2. Kartorium creates a pending api_keys row and emails the recipient a one-time reveal link.
3. The recipient opens /api-key/reveal, signs in through Auth0, confirms the signed-in profile, recipient, organization, delivery ID, reveal-link expiration, and API-key expiration, then reveals the key.
4. Kartorium activates the key, stores only the hashed API key secret, clears the delivery token hash, and shows the raw key one time.
5. The recipient uses the key as a bearer token or as an api_key query parameter against client API routes.

flowchart LR
    ADMIN["Kartorium super admin"] --> PENDING["api_keys status=pending"]
    PENDING --> EMAIL["one-time reveal email"]
    EMAIL --> RECIPIENT["organization member signs in"]
    RECIPIENT --> ACTIVE["api_keys status=active"]
    ACTIVE --> CLIENT["/api/v1/client/*"]
    CLIENT --> AUDIT["api_key_audit_logs"]

Admin Workflow

API keys are managed from /admin/org-settings on the API Keys tab. A Kartorium super admin chooses:

• organization
• recipient
• expiration date
• label
• allowed scopes

Kartorium emails the recipient a delivery link. If email delivery fails, the admin page still shows the delivery link so the super admin can copy it manually. The raw API key is not shown on the admin page.

Calling the Client API

Use the Authorization header for integrations:

GET /api/v1/client/projects
Authorization: Bearer karta_live_example

For browser-only testing, the same key can be passed as api_key:

GET /api/v1/client/projects?api_key=karta_live_example

The query-parameter form is accepted for convenience, but the header form is safer because URLs are more likely to appear in browser history, proxies, and logs.

Security Model

API keys are organization-scoped. A key created for one organization can only access client routes for that organization.

Only Kartorium super admins can create, list, or revoke keys. Organization members can reveal only keys addressed to their Auth0 user ID and only while signed into the matching organization.

Delivery links and API keys both expire. The default API key lifetime is 90 days. Delivery links expire after 7 days and can be used once.

Raw API key secrets are never emailed or stored. Kartorium stores the hashed API key secret, the visible prefix, the recipient user ID, expiration fields, and audit metadata.

Scopes

Each API key carries explicit scopes. The default scope is projects:read. Read and write scopes are separate: a *:read scope cannot create, update, archive, or delete records, and a *:write scope cannot read routes unless the matching read scope is also granted.

Scope	Access
projects:read / projects:write	Projects
scenes:read / scenes:write	Scenes and scene properties
features:read / features:write	Features and feature properties
models:read / models:write	Model metadata
assets:read / assets:write	Asset types, assets, fields, and values
files:read / files:write	File reference metadata
oee:read / oee:write	OEE sites, equipment, events, jobs, and batches
analytics:read / analytics:write	Analytics summaries and saved chart definitions
search:read	Organization-scoped search
organization:read	Basic organization and member metadata

Audit Trail

Every client API request writes an api_key_audit_logs row with the API key ID, organization ID, creating user ID, request IP, user agent, endpoint, method, status code, request ID, required scope, scope decision, and timestamp. Query-string API keys are redacted before the endpoint is stored.

The table registry for api_keys and api_key_audit_logs is maintained in Entity Map.