WorkOS Organizations API 是 WorkOS 平台提供的组织管理接口,用于在应用中创建、查询、更新和删除组织(organization),适合多租户 SaaS 的客户/租户管理。
用途 该 API 面向需要管理组织实体的开发者,典型用途包括:新租户或客户接入(onboarding)、按 ID 或外部 ID 检索组织详情、分页浏览组织目录、修改组织名称/域名/元数据,以及移除租户。
主要能力 端点目录如下:
- POST /organizations:创建组织,用于新租户/客户接入。
- GET /organizations/{id}:按 ID 获取组织详情。
- GET /organizations/external_id/{external_id}:按自有系统的外部 ID 查询。
- GET /organizations:分页列出组织,用于目录浏览。
- PUT /organizations/{id}:更新组织,可修改名称、域名、元数据。
- DELETE /organizations/{id}:删除组织(软删除)。
认证方式 所有请求需在 Authorization 头中携带 API 密钥:Authorization: Bearer sk_live_1234567890abcdef。可将密钥设为环境变量:export WORKOS_API_KEY=sk_live_1234567890abcdef。
使用方式
创建组织时,name 为必填,可选 domains、external_id、metadata。示例请求:
curl -X POST https://api.workos.com/organizations
-H "Authorization: Bearer ${WORKOS_API_KEY}"
-H "Content-Type: application/json"
-d '{
"name": "Acme Corp",
"domains": ["acme.com", "acme.co"],
"external_id": "acme_12345",
"metadata": {
"plan": "enterprise",
"region": "us-west"
}
}'
成功返回 201,响应包含 object、id、name、domains、external_id、metadata、created_at、updated_at 等字段。
按 ID 获取:GET https://api.workos.com/organizations/org_01H1QZ...,返回 200,结构与创建响应相同。 按外部 ID 获取:GET https://api.workos.com/organizations/external_id/acme_12345,返回 200,结构相同。
列表分页:GET "https://api.workos.com/organizations?limit=10&before=org_01H1QZ...",返回 object 为 list,data 为组织数组,list_metadata 含 before/after 游标。使用 before 游标向前翻页,after 游标向后翻页;默认 limit 为 10,最大为 100。
更新组织:PUT https://api.workos.com/organizations/org_01H1QZ...,请求体可含 name、domains、metadata,返回 200 及更新后的组织对象。注意 external_id 创建后不可更改。
删除组织:DELETE https://api.workos.com/organizations/org_01H1QZ...,返回 204 无内容。删除为软删除,SSO/DSYNC 连接仍可检索。
SDK 用法 Node.js SDK: import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS(process.env.WORKOS_API_KEY); const org = await workos.organizations.createOrganization({ name: 'Acme Corp', domains: ['acme.com'], externalId: 'acme_12345', metadata: { plan: 'enterprise' } }); const orgById = await workos.organizations.getOrganization('org_01H1QZ...'); const orgByExternalId = await workos.organizations.getOrganizationByExternalId('acme_12345'); const orgs = await workos.organizations.listOrganizations({ limit: 10, before: 'org_01H1QZ...' }); const updated = await workos.organizations.updateOrganization('org_01H1QZ...', { name: 'Acme Corporation', domains: ['acme.com'] }); await workos.organizations.deleteOrganization('org_01H1QZ...');
Python SDK: from workos import WorkOSClient workos = WorkOSClient(api_key=os.getenv('WORKOS_API_KEY')) org = workos.organizations.create_organization(name='Acme Corp', domains=['acme.com'], external_id='acme_12345', metadata={'plan': 'enterprise'}) org_by_id = workos.organizations.get_organization('org_01H1QZ...') org_by_external_id = workos.organizations.get_organization_by_external_id('acme_12345') orgs = workos.organizations.list_organizations(limit=10, before='org_01H1QZ...') updated = workos.organizations.update_organization('org_01H1QZ...', name='Acme Corporation', domains=['acme.com']) workos.organizations.delete_organization('org_01H1QZ...')
错误码映射
- 400 invalid_request:缺少必填字段(如 name),检查请求体是否包含 name。
- 401 unauthorized:API 密钥无效或缺失,确认 WORKOS_API_KEY 以 sk_ 开头且有效。
- 404 not_found:组织 ID 或 external_id 不存在,核对 ID 或确认组织是否已删除。
- 409 conflict:external_id 重复,使用唯一 external_id 或省略。
- 422 unprocessable_entity:domains 数组中的域名格式无效,确保为有效主机名(如 "acme.com" 而非 "https://acme.com")。
- 429 rate_limit_exceeded:请求过多,实施指数退避;默认限制为 100 请求/秒。
- 500 server_error:WorkOS 内部错误,使用指数退避重试,持续出现请联系支持。
速率限制 默认限制为每个 API 密钥每秒 100 请求。重试策略:指数退避,从 1 秒开始,翻倍至最大 32 秒。可检查 X-RateLimit-Remaining 和 X-RateLimit-Reset 响应头。
验证命令
- 测试 API 密钥认证:GET "https://api.workos.com/organizations?limit=1",预期 HTTP 200 及组织列表(或空数组)。
- 创建测试组织:POST /organizations,请求体含 name 与唯一 external_id,预期返回以 org_ 开头的组织 ID。
- 按外部 ID 检索:GET /organizations/external_id/test_1234567890,预期存在时 HTTP 200,不存在时 HTTP 404。
- 测试分页:GET "https://api.workos.com/organizations?limit=2",预期组织数大于 2 时返回 before 和 after 游标。
- 测试错误处理(无效域名):POST /organizations,domains 含 "not a valid domain!",预期 HTTP 422 及 unprocessable_entity 错误。
常见集成模式
- 同步外部 CRM 到 WorkOS:在系统中创建客户后,调用 createOrganization,将客户 ID 作为 externalId,并在 metadata 中记录 CRM 与 Salesforce ID。
- 从 webhook 查找组织:在 webhook 处理器中,若事件含 organization_id,调用 getOrganization 获取组织,再用 org.external_id 查询自有数据库。
- 批量更新组织元数据:分页列出组织,按 external_id 从 CRM 获取客户信息,再调用 updateOrganization 更新 metadata(如 plan、mrr)。
适用场景 适用于多租户 SaaS 的租户管理、客户接入流程、与 CRM 或自有系统通过 external_id 关联、webhook 事件处理,以及需要按域名或元数据组织客户的场景。
限制与注意事项
- external_id 创建后不可更改。
- 删除为软删除,SSO/DSYNC 连接仍可检索。
- 域名需为裸主机名,不能包含协议或路径。
- 列表分页为游标式,需按 list_metadata 的 after 游标逐页获取直至游标为 null。
- 速率限制默认 100 请求/秒,超限需指数退避。
- 文档建议在实现前先通过 WebFetch 获取最新文档:https://workos.com/docs/reference/organization 及各端点页面。
相关技能 workos-api-sso(为组织配置 SSO 连接)、workos-api-directory-sync(为组织用户配置目录同步)、workos-api-admin-portal(生成组织自助管理门户链接)、workos-domain-verification(验证组织域名所有权)、workos-api-events(订阅组织生命周期事件)。