# Integrations

> Add, list and remove the organization's Hugging Face tokens

`client.integrations` manages the organization's Hugging Face tokens. New runs,
and Hugging Face imports that bring no token of their own, use the default one.

It needs an API key with the opt-in `integrations:write` scope (`*` does not
grant it), made by a Contributor, Admin or Owner of the organization, and not
restricted to workspaces. A key's value goes in once, with `add`, and is never read back.

## List keys

```python
for key in client.integrations.list():
    print(key.provider, key.name, key.last4, key.is_default)
```

**Response**

```json title="list[Integration]"
[
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "huggingface",
  "name": "ci",
  "last4": "9f3a",
  "is_default": true,
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-10-30T12:00:00Z",
  "expires_at": "2027-10-30T12:00:00Z"
}
]
```

Newest first. `provider` is `huggingface`. `last4` is `None` for a key shorter
than 12 characters.

## Add a key

Read the key from the environment or stdin, never from code.

```python
import os

token = client.integrations.add("huggingface", os.environ["HF_TOKEN"], name="ci")
```

| Argument   | Description                                |
| ---------- | ------------------------------------------ |
| `provider` | `"huggingface"`                            |
| `secret`   | The key, a `str` or a `pydantic.SecretStr` |
| `name`     | Up to 15 characters (required)             |

A Hugging Face token starts with `hf_`. The organization's first token becomes
the default. The answer is the key as `list` shows it.

## Remove a key

```python
result = client.integrations.remove(token.id)
print(result.deleted)
```

Workspaces on a removed token move to the default.

## Choose the default token

```python
client.integrations.set_default(token.id)
```

## Errors

| Status | When                                                                                                            |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| 403    | The key lacks `integrations:write`, its creator is a Viewer, or it is a workspace, service or guest's key       |
| 404    | The integration key is not the organization's                                                                   |
| 422    | A bad field: an unknown provider, a missing name or one over 15 characters, or a token without the `hf_` prefix |

A 403 raises `AuthenticationError`, the others `QualiaAPIError`, each with the
server's message. A 422 names the field, never the value you sent.