For the complete documentation index, see llms.txt. This page is also available as Markdown.
API keys and service identities
Issue, store, rotate, and revoke automation credentials safely.
Automation credentials should represent a named service responsibility with the minimum required scope. They must never be embedded in code, screenshots, public documentation, logs, or support tickets.
Before you make the change
Name the service owner, workload, environment, required resources, and review date.
Choose an approved secret manager and rotation process.
Define how to disable the workload safely before revoking the key.
Workspace Settings API Keys header and Create new key action
Open Workspace Settings › API keys and choose Create new key. The key is added to the table with a masked value, Show and Copy controls, an Enabled switch, and Delete. The screenshot intentionally excludes key identifiers and secret values.
Understand the product behavior
API-key management includes create, masked display, reveal, copy, enable/disable, and delete controls.
The Unitlab Python SDK accepts an API key and optional API URL directly, through environment variables, or through CLI configuration. Version 3.0.0 requires Python 3.10 or newer.
Manage a service credential
1
1. Open the correct workspace
Confirm the workspace name and ID, then open Settings › API keys. Keys belong to that workspace boundary.
2
2. Create a new key
Choose Create new key. Treat this as immediate credential issuance and be prepared to store the value before using any other surface.
3
3. Copy into the secret manager
Use Copy key and place the value directly in the approved secret store. Do not reveal it for screenshots, documentation, or troubleshooting.
4
4. Configure the workload
Inject the secret at runtime through the environment or secret manager expected by the pinned SDK, CLI, or HTTP client.
5
5. Test expected access
Run a read-only identity or list operation first, then one scoped representative workflow. Record stable resource IDs and redacted errors.
6
6. Disable before replacement
Use the Enabled switch to stop a key during investigation or a controlled rotation while preserving the row for reconciliation.
7
7. Rotate
Create and deploy the replacement, verify dependent jobs, then disable and delete the superseded key.
8
8. Delete deliberately
Use Delete only after inventorying all dependent workloads and completing the product confirmation. Deleted keys cannot be restored.
Decisions that affect production
Decision
Production guidance
Service identity
Unitlab issues the workspace API key; your operating model should assign that key to a named non-human workload owner rather than a shared person.
Environment
Use separate credentials and resource scope per production, staging, and development environment.
Enabled state
Disable first when you need a reversible containment step; delete after dependencies are reconciled.
Logs
Record resource IDs and redacted errors, never the secret or signed response values.
Incident
Create a replacement and disable the suspected key immediately; inspect affected operations before permanent deletion.
Never paste an API key into GitBook, source control, a screenshot, a chat, or a ticket.
Continue the operating flow
Document the workload owner and resource scope.
Schedule rotation and access review.
Use stable IDs and explicit versions in automated operations.
