WorkOS Python 库

PyPI

The WorkOS library for Python 为使用 Python 编写的应用程序提供了便捷访问 WorkOS API 的方式，托管于 PyPI。

Documentation

请参阅 API Reference 以获取 Python 使用示例。

Installation

需要 Python 3.10+。

pip install workos

快速入门

from workos import WorkOSClient

client = WorkOSClient(api_key="sk_1234", client_id="client_1234")

# List organizations
page = client.organizations.list_organizations()
for org in page.auto_paging_iter():
    print(org.name)

# Create an organization
org = client.organizations.create_organization(name="Acme Corp")
print(org.id)

异步客户端

每个 HTTP API 方法在 AsyncWorkOSClient 上都有一个对应的异步方法。（纯本地实用工具，如 webhook 签名验证、Actions 辅助函数和 PKCE，在两个客户端上均为同步方法。）

from workos import AsyncWorkOSClient

async_client = AsyncWorkOSClient(api_key="sk_1234", client_id="client_1234")

page = await async_client.organizations.list_organizations()
async for org in page.auto_paging_iter():
    print(org.name)

环境变量

当未显式传递凭据时，客户端会从环境中读取凭据：

变量	描述
`WORKOS_API_KEY`	WorkOS API 密钥
`WORKOS_CLIENT_ID`	WorkOS 客户端 ID
`WORKOS_BASE_URL`	覆盖 API 基础 URL（默认为 `https://api.workos.com/`）
`WORKOS_REQUEST_TIMEOUT`	HTTP 超时时间（秒）（默认为 `60`）

可用资源

客户端通过类型化的命名空间属性暴露 WorkOS API：

属性	描述
`client.sso`	单点登录连接和授权
`client.organizations`	组织管理
`client.organization_domains`	组织域名验证
`client.organization_membership`	组织成员管理
`client.user_management`	用户、身份、认证方法、邀请
`client.directory_sync`	目录连接和目录用户/组
`client.groups`	组织组管理
`client.admin_portal`	Admin Portal 链接生成
`client.audit_logs`	审计日志事件、导出和模式
`client.authorization`	细粒度授权 (FGA) 资源、角色、权限和检查
`client.events`	Events API
`client.webhooks`	Webhook 端点管理和事件验证
`client.feature_flags`	功能标志管理（列表、启用/禁用、目标设置）
`client.api_keys`	组织 API 密钥管理
`client.client_api`	客户端 API 令牌生成
`client.connect`	OAuth 应用管理
`client.widgets`	Widget 会话令牌
`client.multi_factor_auth`	MFA 注册和验证（也可作为 `client.mfa` 使用）
`client.pipes`	数据集成
`client.pipes_provider`	组织数据集成配置
`client.radar`	Radar 风险评分
`client.passwordless`	无密码认证会话
`client.vault`	加密数据保险库
`client.actions`	AuthKit Actions 签名验证和响应签名
`client.pkce`	PKCE 代码验证器/挑战辅助工具

分页

分页端点返回 SyncPage[T]（或 AsyncPage[T]），并内置自动分页：

# Iterate through all pages automatically
for user in client.user_management.list_users().auto_paging_iter():
    print(user.email)

# Or work with a single page
page = client.user_management.list_users(limit=10)
print(page.data)        # List of items on this page
print(page.has_more())  # Whether more pages exist
print(page.after)       # Cursor for the next page

错误处理

所有 API 错误均映射到带有丰富上下文的类型化异常类：

from workos import NotFoundError, RateLimitExceededError

try:
    client.organizations.get_organization("org_nonexistent")
except NotFoundError as e:
    print(f"Not found: {e.message}")
    print(f"Request ID: {e.request_id}")
except RateLimitExceededError as e:
    print(f"Retry after: {e.retry_after} seconds")

异常	状态码
`BadRequestError`	400
`AuthenticationError`	401
`AuthorizationError`	403
`NotFoundError`	404
`ConflictError`	409
`UnprocessableEntityError`	422
`RateLimitExceededError`	429
`ServerError`	5xx

重试

客户端在遇到 429 和 5xx 响应、超时以及连接错误时，会自动重试请求最多 3 次（可通过 max_retries 请求选项配置），使用带抖动的指数退避策略并遵守 Retry-After。SDK 会为每个 POST 请求附加一个自动生成的 Idempotency-Key（UUID v4），并在其内部重试中复用相同的密钥。

每请求选项

每个 API 方法都接受 request_options 用于每次调用的覆盖设置（诸如 webhook/Actions 签名验证和 PKCE 工具等本地辅助函数不会发起 HTTP 调用，也不接受 request_options）：

result = client.organizations.list_organizations(
    request_options={
        "timeout": 10,
        "max_retries": 5,
        "extra_headers": {"X-Custom": "value"},
        "idempotency_key": "my-key",
        "base_url": "https://staging.workos.com/",
    }
)

[!NOTE] WorkOS API 目前仅在 Create Audit Log Event 端点（audit_logs.create_event）上支持 Idempotency-Key。其他端点接受该请求头，但不会去重请求，因此在其他位置重试的变更操作仍可能创建重复项。

Type Safety

此 SDK 附带完整的类型注解（py.typed / PEP 561），开箱即可与 mypy、pyright 及 IDE 自动补全配合使用。所有 API 资源模型均为 @dataclass(slots=True) 类，并配备 from_dict() / to_dict() 用于序列化。

SDK Versioning

WorkOS 遵循 Semantic Versioning。破坏性变更仅在主要版本中发布。我们强烈建议在升级主要版本前阅读变更日志。

Beta Releases

WorkOS 拥有处于 Beta 阶段的功能，可通过 Beta 版本访问。我们非常希望您能试用这些功能，并在这些功能达到通用可用性（GA）之前向我们提供反馈。要安装 Beta 版本，请按照上述安装步骤使用 Beta 发布版本进行操作。

Note: Beta 版本之间可能存在破坏性变更。我们建议将软件包版本固定到特定版本。