> 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/get-started/authentication-and-configuration.md).

# Authentication and configuration

Resolve API keys and the API base URL through explicit arguments, environment variables, or CLI configuration.

## 1. Create an API key

![Workspace API key creation 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)

*Workspace Settings › API keys is the credential issuance surface. Create a key there, copy it directly into an approved secret manager, and never reveal it in documentation, logs, command history, or screenshots.*

{% hint style="info" %}
**Outcome:** Resolve API keys and the API base URL through explicit arguments, environment variables, or CLI configuration.
{% endhint %}

## 2. Choose how to configure the client

`UnitlabClient` resolves configuration in this order:

1. Explicit `api_key` or `api_url` constructor argument.
2. `UNITLAB_API_KEY` or `UNITLAB_API_URL` environment variable.
3. Values written by `unitlab configure`.

If no API key is found, the constructor raises `AuthenticationError` before making a request.

The following shell example uses placeholders. Set your real key through your environment or secret manager, and use the API URL assigned to your deployment.

```bash
export UNITLAB_API_KEY="YOUR_API_KEY"
export UNITLAB_API_URL="https://api.unitlab.ai"
```

## 3. Verify access

Save this as `check_connection.py`, then run `python check_connection.py` in your configured environment:

```python
from unitlab import UnitlabClient

client = UnitlabClient()
try:
    print(client.projects.list())
finally:
    client.close()
```

A successful request returns the projects visible to the key. An empty list can be a valid result for an empty workspace. You can make the same read-only check with:

```bash
unitlab project list --json
```

## Optional: save workstation configuration

For a developer workstation, the CLI can persist configuration:

```bash
unitlab configure --api-key "$UNITLAB_API_KEY"
unitlab configure --api-url "https://api.unitlab.ai"
```

Use a workspace-owned service identity where possible. Rotate keys on an explicit schedule and immediately after suspected exposure.

## Troubleshoot the connection

| Result                                        | What to check                                                         |
| --------------------------------------------- | --------------------------------------------------------------------- |
| `AuthenticationError` before a request        | Set an API key using one of the configuration methods above.          |
| Server rejects the credential                 | Confirm the key belongs to the intended workspace and is still valid. |
| Access denied for a resource                  | Check the key's permissions and the target resource ID.               |
| Changes to saved configuration have no effect | Explicit arguments and environment variables take precedence.         |

Continue with the [Python SDK quickstart](/api-sdk-cli/get-started/python-sdk-quickstart.md), [CLI quickstart](/api-sdk-cli/get-started/cli-quickstart.md), or [HTTP API overview](/api-sdk-cli/apis/api-overview.md).

***

> **Continue with Unitlab:** [Unitlab’s data annotation platform](https://unitlab.ai/en/data-annotation)