Phala Cloud Documentation — Private AI on TEE

Authenticate with an API key or a bearer token. Configure credentials directly or through environment variables.

API Key

Environment Variable (Recommended)

Set PHALA_CLOUD_API_KEY in your environment and the SDK picks it up automatically:

export PHALA_CLOUD_API_KEY="phak_your_api_key"

from phala_cloud import create_client

# No api_key argument needed
client = create_client()
me = client.get_current_user()

This is the recommended approach for production deployments and CI/CD pipelines. It keeps credentials out of your source code.

Explicit API Key

Pass the key directly when creating the client:

from phala_cloud import create_client

client = create_client(api_key="phak_your_api_key")

The explicit api_key parameter takes precedence over the environment variable.

Bearer token and workspace

Set bearer_token to authenticate with a bearer token, including an OIDC token. Set workspace to select a workspace by slug. The SDK also reads PHALA_OIDC_TOKEN and PHALA_CLOUD_WORKSPACE.

import os
from phala_cloud import create_client

client = create_client(
    bearer_token=os.environ["PHALA_OIDC_TOKEN"],
    workspace="my-workspace",
)

A nonempty explicit value takes precedence over its environment variable. If both an API key and a bearer token are configured, the API key is used. Workspace names are stripped of surrounding whitespace.

Environment Variables

Variable	Description
`PHALA_CLOUD_API_KEY`	API key for authentication
`PHALA_OIDC_TOKEN`	Bearer token for authentication
`PHALA_CLOUD_WORKSPACE`	Workspace slug
`PHALA_CLOUD_API_PREFIX`	Base URL override (defaults to `https://cloud-api.phala.com/api/v1`)

These variables are read at client creation time. Changing them after the client is created has no effect. For browser-like environments, the SDK supports cookie-based authentication instead of API keys. When enabled, the SDK does not add an API key or bearer authorization header. Authentication relies on cookies managed by the HTTP client.

client = create_client(use_cookie_auth=True)

Cookie-based auth is primarily for internal use. Most users should stick with API key authentication.

revoke_current_api_token

DELETE /tokens/self Call client.revoke_current_api_token() to revoke the API token used for the request. It returns None. The token stops working immediately and cannot be restored. The async client supports await client.revoke_current_api_token(); a safe_revoke_current_api_token variant is also available.

Custom Headers

You can add extra headers to every request. This is useful for tracing, debugging, or passing custom metadata.

client = create_client(
    api_key="phak_your_api_key",
    headers={"X-Request-Source": "my-automation"},
)

Verifying Authentication

Call get_current_user() to verify your credentials are valid:

from phala_cloud import create_client, AuthError

client = create_client()

try:
    user = client.get_current_user()
    print(f"Authenticated as {user.model_dump()}")
except AuthError as e:
    print(f"Auth failed: {e}")

from phala_cloud import create_async_client, AuthError

client = create_async_client()

try:
    user = await client.get_current_user()
    print(f"Authenticated as {user.model_dump()}")
except AuthError as e:
    print(f"Auth failed: {e}")

Bring Your Own HTTP Client

If you need full control over transport settings (proxies, certificates, connection pooling), pass a pre-configured httpx client:

import httpx
from phala_cloud import create_client

http = httpx.Client(
    verify="/path/to/ca-bundle.crt",
    proxy="http://proxy.internal:8080",
)

client = create_client(api_key="phak_your_api_key", http_client=http)

The SDK applies its configured authentication, workspace, and version headers to requests made with the provided client. Configure that client with a base URL for relative API paths. The SDK does not close it automatically. You are responsible for calling http.close() when done.

SDK Overview — installation and quick start
Error Handling — handling AuthError

​API Key

​Environment Variable (Recommended)

​Explicit API Key

​Bearer token and workspace

​Environment Variables

​Cookie-Based Auth

​revoke_current_api_token

​Custom Headers

​Verifying Authentication

​Bring Your Own HTTP Client

​Related

API Key

Environment Variable (Recommended)

Explicit API Key

Bearer token and workspace

Environment Variables

Cookie-Based Auth

revoke_current_api_token

Custom Headers

Verifying Authentication

Bring Your Own HTTP Client

Related