Integrations

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

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