Using API keys

An API key is a credential that lets a server-side integration authenticate to the currently available CatalogIQOS API routes without using a person's interactive sign-in session. API keys are useful for approved system-to-system track reads and background-job requests.

Each key belongs to the active Workspace in which it was created. Requests made with that key can access only records whose catalog belongs to the same Workspace. A key does not grant access to another Workspace, even when a record identifier from that Workspace is supplied.

CatalogIQOS currently provides limited, versioned customer API routes rather than a complete public API. Key-management infrastructure is available, but not every scope shown in the interface maps to a customer endpoint today. Integrations should rely only on the routes and behaviors documented below.

Only Workspace administrators can list, create, or revoke API keys. Open Workspace settings and select API Keys. Members without administrative permission see an access-required message.

API keys are credentials for a Workspace, not personal substitutes for a member account. The creating administrator is recorded on the key and is used as the creator identity for jobs submitted with that key.

1. Open Workspace settings and select API Keys.
2. Enter a descriptive name that identifies the integration or environment.
3. Optionally choose a future expiration date. Leaving expiration blank creates a key without an automatic expiration date.
4. Select at least one scope, granting only what the integration requires.
5. Select Create API Key.
6. Copy the raw key immediately and place it in an approved server-side secret store.

The raw credential is shown only in the creation response. CatalogIQOS stores a SHA-256 hash and a short lookup prefix, not the recoverable raw secret. If the raw key is lost, revoke it and create a replacement.

Keys use the format ciq_<8-character hexadecimal prefix>_<secret>. The prefix may appear in the key list to help identify a credential; it is not sufficient to authenticate.

An optional expiration must be a future date when the key is created. After that timestamp, authentication fails automatically. The API Keys page may continue to list the record for administrative visibility.

Select Revoke to disable a key. Revocation records a timestamp rather than hard-deleting the database record, and subsequent authentication attempts fail. Revoke compromised, retired, or unused credentials immediately. A revoked key cannot be restored through the current interface; create a replacement when needed.

Scopes are additive permission checks, not proof that a resource or operation has a public endpoint. Follow the principle of least privilege: omit every scope the integration does not need.

The current API base path is /api/v1 on your CatalogIQOS deployment. Send the raw key in the HTTP Authorization header using the Bearer scheme:

Authorization: Bearer ciq_<prefix>_<secret>

The following customer-facing routes currently use API-key authentication:

• GET /api/v1/tracks requires tracks:read. Optional query parameters are catalogId, search, and limit; limit is constrained to 1–500 and defaults to 100.
• GET /api/v1/tracks/{trackId} requires tracks:read and returns the matching track only when it belongs to the key's Workspace.
• POST /api/v1/jobs requires jobs:create. The requested job type may require an additional scope as listed above. Supplied track and catalog identifiers are checked against the key's Workspace.

Basic authentication example:

curl "https://YOUR-CATALOGIQOS-HOST/api/v1/tracks?limit=25" \
  -H "Authorization: Bearer $CATALOGIQOS_API_KEY"

Keep the host configurable for your deployment. CatalogIQOS does not currently publish a complete OpenAPI contract or a broader stable endpoint catalog, so confirm intended job payloads with your CatalogIQOS implementation contact before building a production integration.

• Treat API keys like passwords.
• Never commit a key to source control.
• Never expose a key in browser or other client-side code.
• Store keys in server-side environment variables or a managed secrets manager.
• Use only the scopes required by the integration.
• Prefer an expiration date and rotate credentials according to your organization's security policy.
• Use separate keys for separate integrations and environments so one credential can be revoked independently.
• Revoke compromised credentials immediately.
• Do not place raw keys in logs, support requests, screenshots, analytics, or error messages.

• API authentication middleware: PARTIAL — a shared authentication helper is called by the three current /api/v1 routes; there is no global API authentication middleware covering a broader public surface.
• Workspace isolation: IMPLEMENTED — current track and job routes filter or validate track and catalog resources using the authenticated key's Workspace.
• Scope enforcement: PARTIAL — enforcement exists on current routes and job-type gates, but catalog:read and assets:read have no current customer route, while write scopes are job gates rather than general write APIs.
• Key expiration enforcement: IMPLEMENTED — expired keys are excluded during authentication.
• Key revocation: IMPLEMENTED — administrators can timestamp-revoke a same-Workspace key, and revoked keys are excluded during authentication.
• Hashed key storage: IMPLEMENTED — only a SHA-256 hash and lookup prefix are persisted after creation.
• Endpoint authorization: IMPLEMENTED for the three documented /api/v1 routes; this status does not imply coverage for other application routes.
• Audit logging: NOT IMPLEMENTED for key creation, revocation, or authenticated API requests. Last-used time is updated after successful authentication, but that is not a full audit trail.
• Rate limiting: NOT IMPLEMENTED on the current API-key-authenticated routes.
• API versioning: IMPLEMENTED at the path level through /api/v1.
• Stable public endpoint contracts: PARTIAL — versioned routes exist, but no complete public contract or OpenAPI specification is published.

Because audit logging, rate limiting, complete scope-to-endpoint coverage, and a published stable contract remain incomplete, CatalogIQOS should describe this as limited Enterprise API access rather than a fully production-ready general API.

An API key required response means the Authorization header is missing or does not use the Bearer scheme. Invalid API key can mean the key format or secret is wrong, or that the key is expired or revoked. Insufficient API key scope means the credential authenticated but lacks the required permission. A track or catalog may return not found when its identifier does not belong to the key's Workspace.

Review Roles and permissions overview for administrator access and Workspace Profile for Workspace identity and settings. CatalogIQOS does not currently publish a separate complete Enterprise API reference article.