API authentication

Create, store, send, rotate, and validate workspace API keys safely.

Outcome: Create, store, send, rotate, and validate workspace API keys safely.

Obtain a workspace key

Open Workspace Settings → API keys, create a key for the intended integration, and copy it directly into the approved secret manager. Effective access is constrained by the associated identity, workspace role, and resource permissions.

Workspace API keys entry point

Create the credential in Workspace Settings, then move it directly into an approved secret manager.

Send the key

Authorization: Api-Key YOUR_API_KEY
Accept: application/json
Content-Type: application/json

curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/projects/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"

Validate and rotate

• Validate a new key with a read-only request before enabling mutations.

• Use separate identities and keys for development, staging, and production.

• Rotate on schedule and immediately after suspected exposure.

• Deploy and validate the new secret before revoking the old key.

• Never place keys in source, screenshots, URLs, logs, artifacts, or shell history.

Failure	Meaning	Action
401	Key is absent, malformed, expired, or rejected	Stop and repair credential configuration
403 permission denial	Identity cannot act on the resource	Review role and resource access
Other 403	Entitlement or subscription blocks the operation	Review entitlement; do not retry unchanged

If a key appears in a ticket, chat, log, recording, screenshot, or repository, treat it as exposed and rotate it immediately.

Request operating contract

Concern	Required behavior
Execution surface	TLS-verified client using the reviewed current public /api/sdk/... route contract.
Identity	Least-privilege workspace service identity; secrets remain outside code and logs.
Request boundary	URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.
Success evidence	Response identifiers, read-after-write verification, and separate processing status for Batch Queues.

Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.

---

Explore related Unitlab capabilities: AI training-data annotation