Integrations

client.integrations manages the organization’s Hugging Face tokens. New runs use the default one.

It needs an API key with the opt-in integrations:write scope (* does not grant it), made by an 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

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

Response

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.

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

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

Workspaces on a removed token move to the default.

Choose the default token

client.integrations.set_default(token.id)

Errors

Status	When
403	The key lacks integrations:write, its creator is not an Admin or Owner, 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.