API Keys
API keys are workspace-level credentials for public Carmen API calls and, where enabled, selected backend API operations.
Multiple Keys per Workspace
A workspace can have multiple API keys. Use separate keys for separate applications, environments or services. This makes rotation and permission changes safer because one integration can be changed without affecting all others.
Product Access
Each API key can be enabled or disabled per product. For example, one key can be allowed to call only Vehicle and Transportation & Cargo APIs, while another key can be limited to Carmen ID Recognition.
Public API requests are checked against:
- the API key value,
- the workspace that owns the key,
- the product enabled on the key,
- the workspace subscription or credit entitlement,
- the configured API version and engine overrides.
API Version Override
The Dashboard can pin a key to a specific API response version. This is useful when an existing client depends on an older JSON response shape.
The same version can also be requested per call with the x-api-version header.
When both are used, the request-level behavior should be treated as integration
specific; keep one strategy per client to avoid confusion.
Engine Parameter Overrides
Engine parameter overrides apply advanced recognition settings to requests made with the key. Use them only when the target scenario is known, because they can change recognition accuracy, runtime and result structure.
Common examples include:
- Region of Interest (ROI), which restricts recognition to a polygon in the original image coordinate space.
- timeout or engine-specific limits, where supported by the selected product.
Backend Role
An API key may also carry a backend role for workspace-scoped backend API operations such as usage, storage, events or workspace management. Backend role access is still limited to the key's own workspace.
Do not use a highly privileged backend role for a public client-side application.