Management API#

Management API は Workspace、Environment、Client、エンドユーザーなどをサーバーから管理する API である。利用には Management API key または Dashboard session を使う。

接続と認証#

本番の base URL は https://api.zeroword.smartcrab.ai/v1 である。Management API key は sk_live_... 形式のみが発行される。Authorization: Bearer sk_live_… で送る。API key はサーバー側にだけ保存し、ブラウザーやモバイルアプリへ配布しない。

curl 'https://api.zeroword.smartcrab.ai/v1/workspaces?limit=10' \
  -H 'Authorization: Bearer sk_live_…'

API key の発行・失効#

Dashboard の Workspace メニュー「API キー」(/w/<workspaceId>/api-keys) から発行するか、POST /v1/api-keys を呼び出す (以降の endpoint 表では /v1 を省略する)。作成レスポンスの secret は一度だけ表示されるため、その場で安全な secret store に保存する。GET /api-keys は secret を返さない。期限を expires_at で指定でき、POST /api-keys/{apiKeyId}/revoke で失効させる。期限のない key は expires_at: null になる。

API key は発行時に scopes を明示する。Environment を environment_id に指定するとその Environment に固定され、指定しなければ同じ Workspace 内で使える Workspace-scoped key となる。key の workspace_id は固定され、key 自身がその Workspace context になる。

Method / path	必須 field・query	Scope
`GET /api-keys`	query: `workspace_id`; 任意: `environment_id`, `limit`, `cursor`	`api_keys:read`
`POST /api-keys`	body: `workspace_id`, `name`, 1 件以上の `scopes`; 任意: `environment_id`, `expires_at`	`api_keys:write`
`POST /api-keys/{apiKeyId}/revoke`	path: `apiKeyId` (`mky_...`)	`api_keys:write`

API key 発行時と一覧取得時の workspace_id は認証 context の Workspace と一致させる。一致しない場合は 400 invalid_request、detail は workspace_id must match X-Workspace-Id となる。Dashboard session の API 呼び出しでは X-Workspace-Id: <workspaceId> が必須であり、選択中の Workspace として照合される。一方、API key の呼び出しでは key の固定 Workspace が使われ、X-Workspace-Id は不要であり無視される。Dashboard session では header を省略しない。

Scopes#

Scope は次のとおりである。必要最小限のものを発行する。:write は read を暗黙に含まない。secret rotation、credential 操作、user delete などは個別 scope を要求する。

Workspace: workspaces:read, workspaces:write, workspace_members:read
Project: projects:read, projects:write
Environment: environments:read, environments:write
Client: clients:read, clients:write, clients:rotate_secret
Connection: connections:read, connections:write
Domain: domains:read, domains:write
User: users:read, users:write, users:block, users:delete
User identities: user_identities:read, user_identities:write
User passkeys: user_passkeys:read, user_passkeys:write
User sessions: user_sessions:read, user_sessions:write
Import/export job: user_data_jobs:read, user_data_jobs:write
Webhook: webhooks:read, webhooks:write, webhooks:rotate_secret, webhooks:test
Audit/usage: audit_events:read, usage:read
OAuth token introspection: introspect (POST /oauth2/introspect に X-Management-API-Key: <secret> として提示する。Environment-scoped key は issuer の Environment と environment_id が一致する場合に有効。environment_id を省略した Workspace-scoped key は同じ Workspace の Environment で使える。Scope 不足または Environment 不一致は {"active":false} を返す。Introspection を参照)
Billing: billing:read, billing:write
API key: api_keys:read, api_keys:write
Impersonation: impersonation:create (Dashboard session の Owner/Admin のみ利用可能)

Scope が足りない認証済みのリクエストは 403 / insufficient_scope となる。

共通仕様#

List route は limit / cursor による cursor pagination を使う。limit の既定値は 25、最大値は 100。続きがある場合は next_cursor、最後は null が返る。
OpenAPI で Idempotency-Key を受け付ける write route では、同じ Workspace、method、route、key、canonical JSON body の組み合わせで再送すると最初の response を返す。同じ key を method、route、body のいずれかが異なる request に使うと 409 idempotency_key_conflict となる。key は最大 255 文字である。@auth-platform/management-client は write ごとに UUID を生成し、WriteOptions.idempotencyKey で上書きできる。Environment settings、Theme、Impersonation の各 route は idempotency に対応しない。
ETag を返す単体 resource の更新・削除は If-Match で条件付きにできる。ETag 不一致は 412 precondition_failed。Theme の PUT も If-Match を使う。
成功・エラーの全レスポンスに X-Request-Id が付く。ETag 対応レスポンスには ETag も付く。
Error body は RFC 9457 Problem Details (application/problem+json) で、type, title, status, code, request_id と、あれば detail を含む。一般的な例は認証失敗 401, Scope 不足 403, 不存在 404, state/unique conflict 409, ETag 不一致 412, 期限切れ download 410, rate limit 429 である。429 と 5xx は一時的な失敗として扱い、write を再試行するときは同じ Idempotency-Key を使う。

全 path は base URL の /v1 に続けて指定する。表中の field は主要な絞り込み・作成 field であり、完全な request/response schema は specs/management-api.openapi.yaml にある。

Resource reference#

Workspaces / members#

GET /workspaces は Dashboard session では member になっている Workspace を返し、Workspace-scoped API key では key の Workspace だけを返す。POST /workspaces は Dashboard session 専用で、作成者が Owner になる。Management API key ではこの route を使えない。

Method / path	必須 field・query	Scope / access
`GET /workspaces`	任意: `limit`, `cursor`, `status`	`workspaces:read`
`POST /workspaces`	body: `name`; 任意: `slug`	Dashboard session のみ
`GET /workspaces/{workspaceId}`	path: `workspaceId`	`workspaces:read`
`PATCH /workspaces/{workspaceId}`	body: `name`, `slug` のいずれか	`workspaces:write`
`GET /workspaces/{workspaceId}/members`	path: `workspaceId`; 任意: `limit`, `cursor`	`workspace_members:read`

Workspace 更新で status は変更できない。Member response は platform_user_id, role, created_at, updated_at のみを含み、credential は含まない。

Projects#

Method / path	必須 field・query	Scope
`GET /projects`	query: `workspace_id`; 任意: `limit`, `cursor`	`projects:read`
`POST /projects`	body: `workspace_id`, `name`; 任意: `slug`	`projects:write`
`GET /projects/{projectId}`	path: `projectId`	`projects:read`
`PATCH /projects/{projectId}`	body: `name`, `slug` のいずれか	`projects:write`
`DELETE /projects/{projectId}`	path: `projectId`	`projects:write`

query/body の workspace_id は認証 context の Workspace と一致させる。DELETE は Project の論理削除であり、response は { "id": "…", "deleted": true } である。

Environments / settings / theme / RP migration#

Environment の issuer, interaction_domain, rp_id は ID とプラットフォーム domain から導出され、create body では指定しない。

Method / path	必須 field・query	Scope
`GET /environments`	query: `project_id`; 任意: `type`, `limit`, `cursor`	`environments:read`
`POST /environments`	body: `project_id`, `type` (`test` / `production`), `name`	`environments:write`
`GET /environments/{environmentId}`	path: `environmentId`	`environments:read`
`PATCH /environments/{environmentId}`	body: `name`, `status` (`active` / `suspended`) のいずれか	`environments:write`
`DELETE /environments/{environmentId}`	path: `environmentId`	`environments:write`
`GET /environments/{environmentId}/settings`	—	`environments:read`
`PATCH /environments/{environmentId}/settings`	body: `impersonation_enabled`	`environments:write`; `If-Match` / `Idempotency-Key` 非対応
`GET /environments/{environmentId}/theme`	—	`environments:read`
`PUT /environments/{environmentId}/theme`	body: theme schema object; `If-Match`	`environments:write`; `Idempotency-Key` 非対応
`GET /environments/{environmentId}/theme/preview-css`	—	`environments:read`
`GET /environments/{environmentId}/rp-migration`	—	`environments:read`
`POST /environments/{environmentId}/rp-migration/disable-legacy`	body: `confirm_rp_id`	`environments:write`

Environment の DELETE は status を deleted にする。PATCH では deleted にできない。RP migration の disable-legacy は不可逆で、confirm_rp_id は旧 RP ID に一致させる必要がある。Theme schema と RP ID・Hosted Login の関係は Hosted Login を参照する。

Clients#

Method / path	必須 field・query	Scope
`GET /clients`	query: `environment_id`; 任意: `client_type`, `limit`, `cursor`	`clients:read`
`POST /clients`	body: `environment_id`, `client_type`, `name`, `token_endpoint_auth_method`; redirect/origin/scope などは任意	`clients:write`
`GET /clients/{clientId}`	path: `clientId`	`clients:read`
`PATCH /clients/{clientId}`	body: `name`, `redirect_uris`, `post_logout_redirect_uris`, `allowed_origins`, `allowed_scopes`, `allowed_resources`, `token_endpoint_auth_method`, `require_pkce`, `status`, `mobile_app` のいずれか	`clients:write`
`DELETE /clients/{clientId}`	path: `clientId`	`clients:write`
`POST /clients/{clientId}/rotate-secret`	path: `clientId`	`clients:rotate_secret`

client_type は web_bff, web_spa, react_native。token_endpoint_auth_method が none 以外の Client では client_secret を作成または rotation の response で一度だけ表示する。public client (none) には secret を発行しない。List/get/update response は secret を返さない。 PATCH の body field はすべて任意である。allowed_resources は HTTPS URL を最大 20 件まで指定できる。mobile_app は react_native Client の設定 object で、app_scheme、ios_bundle_id、ios_team_id、android_package_name、android_sha256_fingerprints、universal_link_host を持つ。null を指定すると設定を解除する。require_pkce の値にかかわらず、Authorization Server は全 Client に PKCE S256 を要求する。

Method / path	必須 field・query	Scope
`GET /connections`	query: `environment_id`; 任意: `provider`, `limit`, `cursor`	`connections:read`
`POST /connections`	body: `environment_id`, `provider`, `mode`, `provider_key`, `provider_client_id`, `provider_client_secret`; generic OIDC では `issuer`	`connections:write`
`PATCH /connections/{connectionId}`	`issuer`, `provider_client_id`, `provider_client_secret`, `scopes`, `profile_mapping`, `status`, `owner_confirmed` のいずれか	`connections:write`
`DELETE /connections/{connectionId}`	path: `connectionId`	`connections:write`

provider は google, apple, github, microsoft, generic_oidc。mode: "managed" は Zeroword の共有 OAuth application を使い、mode: "byo" は customer-owned provider app の Client ID/Secret を使う。provider_client_secret は create/update の write-only input であり、response に一切含まれない。generic_oidc は Workspace Owner が Dashboard で確認するか、connections:write Scope を持つ caller が PATCH /connections/{connectionId} に {"owner_confirmed": true} を送信するまで login に利用できない。issuer を変更すると確認状態が解除される。同じ PATCH で owner_confirmed: true を指定した場合は、その変更が明示的な確認となる。

Domains#

Method / path	必須 field・query	Scope
`GET /domains`	query: `environment_id`; 任意: `status`, `limit`, `cursor`	`domains:read`
`POST /domains`	body: `environment_id`, `hostname`; 任意: `rp_enabled`	`domains:write`
`GET /domains/{domainId}`	path: `domainId`	`domains:read`
`PATCH /domains/{domainId}`	body: `rp_enabled`	`domains:write`
`DELETE /domains/{domainId}`	path: `domainId`	`domains:write`
`POST /domains/{domainId}/retry-validation`	path: `domainId`	`domains:write`

作成後は pending となり、validation の進行は status / validation_errors で確認する。Domain の custom host、Hosted Login、RP ID への影響は Hosted Login を参照する。

Users / identities / passkeys / sessions#

全ての user route は environment_id query が必要である。GET /users は status / search で絞り込みできる。

Method / path	必須 field・query	Scope
`GET /users`	query: `environment_id`; 任意: `status`, `search`, `limit`, `cursor`	`users:read`
`POST /users`	body: `environment_id`, `email`; 任意: `email_verified`, `name`, `avatar_url`, `locale`, `timezone`, `metadata`	`users:write`
`GET /users/{userId}`	path: `userId`; query: `environment_id`	`users:read`
`PATCH /users/{userId}`	query: `environment_id`; profile / `metadata` fields	`users:write`
`DELETE /users/{userId}`	query: `environment_id`; `If-Match` 任意	`users:delete`
`POST /users/{userId}/block`	query: `environment_id`; body の `reason` は任意	`users:block`
`POST /users/{userId}/unblock`	query: `environment_id`	`users:block`
`GET /users/{userId}/identities`	query: `environment_id`, `limit`, `cursor`	`user_identities:read`
`DELETE /users/{userId}/identities/{identityId}`	query: `environment_id`	`user_identities:write`
`GET /users/{userId}/passkeys`	query: `environment_id`, `limit`, `cursor`	`user_passkeys:read`
`DELETE /users/{userId}/passkeys/{passkeyId}`	query: `environment_id`	`user_passkeys:write`
`GET /users/{userId}/sessions`	query: `environment_id`, `limit`, `cursor`	`user_sessions:read`
`DELETE /users/{userId}/sessions/{sessionId}`	query: `environment_id`	`user_sessions:write`
`DELETE /users/{userId}/sessions`	query: `environment_id`	`user_sessions:write`

User の DELETE は pending_deletion への移行である。PATCH /users/{userId} では email を変更できない。Identity / passkey / session response は secret credential や private key material を含まない。

User import / export jobs#

Method / path	必須 field・query	Scope
`POST /user-import-jobs`	body: `environment_id`, `format` (`json` / `csv`), `source_url` (HTTPS)	`user_data_jobs:write`
`GET /user-import-jobs/{jobId}`	path: `jobId`	`user_data_jobs:read`
`GET /user-import-jobs/{jobId}/errors`	path: `jobId`	`user_data_jobs:read`
`POST /user-export-jobs`	body: `environment_id`, `target_user_id`	`user_data_jobs:write`
`GET /user-export-jobs/{jobId}`	path: `jobId`	`user_data_jobs:read`
`GET /user-export-jobs/{jobId}/download`	path: `jobId`	`user_data_jobs:read`

POST response は job resource (pending, processing, completed, failed) を返す。Import source の fetch や export artifact 作成はこの request 中に実行されるため、返却時点ですでに completed または failed の場合がある。成功した export の download_url は期限付きである。Import error report と export download route は Management API key/session で認証し、user_data_jobs:read scope を要求する。

Webhooks / deliveries / test#

Method / path	必須 field・query	Scope
`GET /webhooks`	query: `environment_id`; 任意: `limit`, `cursor`	`webhooks:read`
`POST /webhooks`	body: `environment_id`, `url`, 1 件以上の `event_types`	`webhooks:write`
`PATCH /webhooks/{webhookId}`	body: `url`, `event_types`, `status` のいずれか	`webhooks:write`
`DELETE /webhooks/{webhookId}`	path: `webhookId`	`webhooks:write`
`GET /webhooks/{webhookId}/deliveries`	path: `webhookId`; 任意: `status`, `occurred_after`, `occurred_before`, `limit`, `cursor`	`webhooks:read`
`POST /webhooks/{webhookId}/test`	body の `event_type` は任意	`webhooks:test`
`POST /webhooks/{webhookId}/rotate-secret`	path: `webhookId`	`webhooks:rotate_secret`

作成と secret rotation では signing secret を response で一度だけ表示する。List/update/delete/deliveries から secret は取得できない。Delivery history は 90 日保持され、body/header/signature は含まず status、attempt、response status code、duration などを返す。Event envelope、署名検証、再送については Webhooks を参照する。

Audit events#

Method / path	必須 field・query	Scope
`GET /audit-events`	query: `environment_id`; 任意: `actor_type`, `action`, `subject_type`, `subject_id`, `result`, `created_after`, `created_before`, `limit`, `cursor`	`audit_events:read`

Audit event は追記専用で、Management API から update/delete できない。Response に内部 routing ID や credential は含まれない。

Usage / MAU#

Method / path	必須 field・query	Scope
`GET /usage/mau`	任意: `billing_month` (`YYYY-MM`), `environment_id`	`usage:read`

Workspace の MAU 集計、30,000 MAU free tier、threshold 到達状況、billing / grace-period state を返す。environment_id を指定するとその Environment の値に絞る。

Billing#

Method / path	必須 field・query	Scope
`POST /billing/checkout-session`	body: `success_url`, `cancel_url` (HTTPS)	`billing:write`
`POST /billing/portal-session`	body: `return_url` (HTTPS)	`billing:write`

Checkout response は checkout_url, expires_at、portal response は portal_url を返す。Stripe customer/subscription IDs は返さない。30,000 MAU を超えて継続利用するための支払い有効化に使う。

Impersonation#

Method / path	必須 field・query	Scope / access
`POST /impersonation?environment_id={environmentId}`	body: `user_id`, `reason` (10–1000 文字), `duration_minutes` (1–15)	`impersonation:create`; Owner/Admin の Dashboard session のみ
`POST /impersonation/stop`	—	認証済み request。active impersonation cookie を消去

Environment settings で impersonation を明示的に有効化してから開始する。API key では開始できない。Start response に actor、対象 user、理由、期限、禁止 Scope が含まれる。Impersonation の開始・終了は Dashboard session の操作であり、API key による Resource 管理とは別に扱う。

TypeScript client#

Node.js の Management API client、Result return convention、pagination helper、全 method は @auth-platform/management-client を参照する。