> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/security/api-keys-and-service-identities.md).

# API keys and service identities

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](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F327PnSQHyZTbfbLyJSpN%2Fapi-keys-entry.png?alt=media\&token=dba8de6a-29ac-4957-a68f-74e283028da4)

*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

{% stepper %}
{% step %}

#### 1. Open the correct workspace

Confirm the workspace name and ID, then open Settings › API keys. Keys belong to that workspace boundary.
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### 4. Configure the workload

Inject the secret at runtime through the environment or secret manager expected by the pinned SDK, CLI, or HTTP client.
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### 6. Disable before replacement

Use the Enabled switch to stop a key during investigation or a controlled rotation while preserving the row for reconciliation.
{% endstep %}

{% step %}

#### 7. Rotate

Create and deploy the replacement, verify dependent jobs, then disable and delete the superseded key.
{% endstep %}

{% step %}

#### 8. Delete deliberately

Use Delete only after inventorying all dependent workloads and completing the product confirmation. Deleted keys cannot be restored.
{% endstep %}
{% endstepper %}

### 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.                             |

{% hint style="warning" %}
Never paste an API key into GitBook, source control, a screenshot, a chat, or a ticket.
{% endhint %}

### 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.