> 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/api-sdk-cli/apis/api-authentication.md).

# API authentication

{% hint style="info" %}
**Outcome:** Create, store, send, rotate, and validate workspace API keys safely.
{% endhint %}

### 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](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)

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

### Send the key

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

```bash
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 |

{% hint style="danger" %}
If a key appears in a ticket, chat, log, recording, screenshot, or repository, treat it as exposed and rotate it immediately.
{% endhint %}

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

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}