Client API Keys

Kartorium client API keys let trusted organization members access client-facing project data without using a browser session. Keys are scoped to one organization and are provisioned by Kartorium administrators.

Delivery Flow

1. A Kartorium administrator selects an organization, recipient, label, expiration date, and allowed scopes.
2. Kartorium emails the recipient a one-time reveal link.
3. The recipient signs in, confirms the organization and key details, then reveals the key.
4. Kartorium stores a non-reversible verifier for the key and shows the raw key one time.
5. The recipient uses the key as a bearer token against client API routes.

flowchart LR
    ADMIN["Kartorium administrator"] --> EMAIL["one-time reveal email"]
    EMAIL --> RECIPIENT["organization member signs in"]
    RECIPIENT --> ACTIVE["active API key"]
    ACTIVE --> CLIENT["Client API"]
    CLIENT --> AUDIT["audit log"]

Admin Workflow

Kartorium administrators choose:

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

Kartorium emails the recipient a delivery link. If email delivery fails, Kartorium can provide the delivery link through a secure approved channel. The raw API key is only shown to the recipient during reveal.

Calling the Client API

Production Client API requests use this base URL:

https://kartorium.app/api/v1

Append the client route to that base. For example, the full project list URL is https://kartorium.app/api/v1/client/projects.

Use the Authorization header for integrations:

GET /api/v1/client/projects
Authorization: Bearer <your-api-key>

Do not put API keys in URLs. URLs are more likely to appear in browser history, proxies, screenshots, and logs.

For project, scene, feature, GeoJSON, and Python examples, see Client API Project Data.

Security Model

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

Only Kartorium administrators can create, list, or revoke keys. Organization members can reveal only keys addressed to their signed-in account and 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 keys are never emailed or stored. Kartorium stores only the information needed to validate, expire, revoke, and audit key use.

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, scene properties, and 360 scene media references stored as scene properties
features:read / features:write	Features, feature properties, feature custom fields, and feature-level scripted interactions
models:read / models:write	Model metadata
assets:read / assets:write	Asset types, assets, fields, and values
files:read / files:write	File uploads and organization-scoped file reference metadata
search:read	Organization-scoped search
organization:read	Basic organization and member metadata

Audit Trail

Every client API request writes audit metadata that includes the key record, organization, endpoint, method, status, request context, and scope decision.

Builder Client Routes

These routes expose the Builder project hierarchy and related metadata:

Route	Data
/projects and /projects/:projectID	Project records in the key’s organization
/projects/:projectID/scenes and /scenes/:sceneID	Scenes inside a project
/scenes/:sceneID/properties, /scenes/:sceneID/media, and /scenes/:sceneID/links	Scene properties, 360 scene media, and scene-to-scene navigation links
/projects/:projectID/features, /scenes/:sceneID/features, and /features/:featureID	Features in a project or scene, including feature-level scripted interactions
/features/:featureID/custom-fields	Feature custom fields shown in Viewer details
/features/:featureID/properties	Feature properties, including map display settings and coordinate strings. Marker display keys include displayType, icon, text, color, backgroundColor, backgroundShape, and size; create missing properties with POST and change existing defaults with PATCH.
/models, /models/:modelID, and /projects/:projectID/models	Model metadata
/asset-types, /asset-types/:assetTypeID, /assets, and /assets/:assetID	Asset Manager structure and entries
/files/upload, /files, and /files/:fileID	Upload files, list organization file references, and delete file reference metadata. API clients cannot register caller-supplied storage paths.
/organization	Basic organization member metadata
/search/assets	Organization-scoped asset search