Management API client SDK (@auth-platform/management-client)#

Node.js 22 以降で Management API を呼び出す型付き Client である。API key をサーバー側に保持し、ブラウザーやモバイルアプリへ含めない。API の認証・Scope・path は Management API を参照する。

インストールと Client の作成#

pnpm add @auth-platform/management-client

import { createManagementClient } from "@auth-platform/management-client";

const apiKey = process.env.AUTH_PLATFORM_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("AUTH_PLATFORM_API_KEY is required");
}

const client = createManagementClient({
  baseUrl: "https://api.zeroword.smartcrab.ai/v1",
  apiKey,
});

baseUrl は http: / https: のみ受け付ける。不正 URL、その他の protocol、空 key は TypeError となる。全 request で Authorization: Bearer <apiKey> を送り、key を log しない。API key 自体に Workspace context が固定されるため、この client に X-Workspace-Id option はない。Dashboard session cookie 認証には使わない。

Result とレスポンス#

各 method は throw ではなく ResultAsync<T, ManagementClientError> (Promise<Result<T, E>>) を返す。Result は { type: "Success", value } または { type: "Failure", error } の tagged union である。

import { isFailure } from "@auth-platform/management-client";

const result = await client.listClients({ environment_id: "env_…", limit: 10 });
if (isFailure(result)) {
  if (result.error.type === "api_error") {
    console.error(result.error.status, result.error.code, result.error.requestId);
  } else {
    console.error(result.error.type);
  }
} else {
  console.log(result.value.data.items);
  console.log("request id:", result.value.requestId);
}

成功時の value は ManagementResponse<T> であり、data、requestId、etag を持つ。Response body は Management contract の schema で検証される。ETag 対応 route は etag を返し、次の write の If-Match に利用できる。

ApiError の requestId は support への問い合わせに使う。認証・Scope・HTTP status の扱いは Problem Details を参照する。

Write options#

各 write method は WriteOptions を受け付ける。

const current = await client.getClient("cli_…");
if (isFailure(current)) throw current.error;

const writeOptions = current.value.etag === undefined
  ? { idempotencyKey: crypto.randomUUID() }
  : { idempotencyKey: crypto.randomUUID(), ifMatch: current.value.etag };

const updated = await client.updateClient(
  "cli_…",
  { name: "New client name" },
  writeOptions,
);

idempotencyKey を省略すると SDK が write ごとに UUID を生成する。同一 write を再送する場合は、最初の request と同じ idempotencyKey を渡す。ifMatch を指定すると If-Match header に送る。Resource が変わっていた場合、server は 412 precondition_failed を返す。Theme、Environment settings、Impersonation route は SDK に method がなく、Idempotency-Key にも対応しない。

Pagination#

List method は page response (data.items, data.next_cursor) を返す。paginate は cursor をたどり、各 page の Result を AsyncGenerator として返す。Failure は一度 yield して終了する。collectAll は全 page の item を配列に集める。既定で 100 page を上限とし、必要に応じて maxPages を指定する。

import { collectAll, isFailure } from "@auth-platform/management-client";

const projects = await collectAll((cursor) =>
  client.listProjects({
    workspace_id: "wsp_…",
    limit: 50,
    ...(cursor === null ? {} : { cursor }),
  }),
);

if (isFailure(projects)) {
  console.error(projects.error);
} else {
  console.log(projects.value);
}

ページごとの response metadata が必要な場合は paginate を使う。

import { isFailure, paginate } from "@auth-platform/management-client";

for await (const page of paginate((cursor) =>
  client.listProjects({
    workspace_id: "wsp_…",
    limit: 50,
    ...(cursor === null ? {} : { cursor }),
  }),
)) {
  if (isFailure(page)) {
    console.error(page.error);
    break;
  }
  for (const project of page.value.data.items) console.log(project.id);
}

Method reference#

create / update / list の入力型と WriteOptions は package root から export される（例: ClientCreateInput、UserListParams、WebhookCreateInput）。

createWorkspace は Dashboard session 専用 route に対応するため、Management API key で呼ぶと認証されない。SDK には API key create/list/revoke、Environment settings/theme、Impersonation、import error report download、export download の method はない。これらの HTTP path と Scope は Management API resource reference を参照する。