Mengelola WIF dengan Admin API

Admin API memungkinkan Anda membuat dan mengelola sumber daya Workload Identity Federation secara terprogram: akun layanan, federation issuer, dan federation rule. Gunakan API ini untuk menyimpan konfigurasi federasi Anda dalam infrastructure as code, menyediakannya dari CI, dan mereproduksinya di berbagai organisasi alih-alih mengklik satu per satu di Claude Console. Endpoint ini berbagi prefiks path /v1/organizations dengan bagian lain dari Admin API.



Prasyarat

Setiap permintaan di halaman ini diautentikasi dengan OAuth bearer token yang membawa scope org:admin. Scope ini hanya diberikan kepada anggota organisasi dengan peran admin, owner, atau primary owner, dan memberikan akses ke seluruh organisasi: pengikatan workspace apa pun akan diabaikan. Ada dua cara untuk mendapatkan token, dan keduanya membawa izin yang berbeda: token dari login Anda sendiri bertindak sebagai pengguna, sedangkan token terfederasi bertindak sebagai akun layanan dan tidak dapat melakukan setiap operasi di halaman ini.

Interaktif (terminal Anda): Login dengan CLI ant menggunakan profil khusus, dengan meminta scope org:admin (lihat Akses admin), lalu ekspor bearer token:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_OAUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

Token interaktif berumur pendek; jika permintaan mulai mengembalikan 401, jalankan kembali perintah ekspor (perintah ini menyegarkan token secara otomatis).

Workload (CI dan otomatisasi): Buat federation rule dengan oauth_scope: org:admin yang menargetkan akun layanan dengan organization_role bernilai admin. Rule itu sendiri harus dibuat di Claude Console: memberikan akses admin organisasi kepada sebuah workload adalah tindakan manusia yang disengaja, bukan sesuatu yang dapat di-bootstrap sendiri oleh otomatisasi. Bagian berikutnya memandu Anda melalui penyiapan sekali-per-organisasi ini.



Bootstrap workload untuk mengelola WIF

Satu rule yang dibuat di Console sudah cukup untuk menempatkan sisa konfigurasi federasi Anda di bawah infrastructure as code: berikan scope org:admin kepada satu workload tepercaya, dan biarkan workload tersebut mengelola federation issuer dan setiap federation rule dengan scope workspace melalui API ini.

Untuk operasi yang dapat dan tidak dapat dilakukan oleh token yang dicetak workload, lihat Izin dan batasan. Jika Anda sudah membuat issuer, akun layanan, atau rule dengan wizard Connect workload, daftarkan semuanya dengan endpoint berikut dan impor ke dalam state infrastructure-as-code Anda alih-alih membuatnya ulang.



Autentikasi

Semua endpoint berada di bawah https://api.anthropic.com/v1/organizations/. Setiap permintaan ke endpoint federasi dan akun layanan memerlukan header versi API dan bearer token:

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Kunci Admin API tidak diterima pada endpoint ini; contoh x-api-key di halaman Admin API tidak berlaku di sini.



Akun layanan

Akun layanan (svac_...) adalah identitas non-manusia yang diwakili oleh token terfederasi. Atur organization_role ke developer.

# Membuat akun layanan
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Menampilkan daftar akun layanan
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Mengarsipkan akun layanan
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Endpoint create mengembalikan akun layanan baru:

{
  "id": "svac_...",
  "name": "inference-worker",
  "organization_role": "developer",
  "created_at": "...",
  "type": "service_account",
  "...": "..."
}

Untuk membaca atau memperbarui satu akun layanan, gunakan GET dan POST pada /v1/organizations/service_accounts/{service_account_id}. Akun layanan harus menjadi anggota workspace sebelum token terfederasi dapat bertindak di dalamnya. Setiap akun layanan memiliki keanggotaan implisit di workspace default organisasi Anda; tambahkan keanggotaan eksplisit untuk workspace lain dengan GET, POST, dan DELETE pada /v1/organizations/service_accounts/{service_account_id}/workspaces, di mana DELETE menargetkan .../workspaces/{workspace_id}.



Federation issuer

Federation issuer (fdis_...) mendaftarkan identity provider OIDC ke organisasi Anda. Field jwks adalah discriminated union yang mengontrol bagaimana Anthropic mengambil signing key dari provider:

# Daftarkan issuer (GitHub Actions, dengan penemuan JWKS)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# Tampilkan daftar issuer
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arsipkan issuer
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Untuk membaca atau memperbarui satu issuer, gunakan GET dan POST pada /v1/organizations/federation_issuers/{issuer_id}. Pemanggil OAuth tidak dapat memperbarui issuer yang mendukung rule dengan oauth_scope selain workspace:developer atau workspace:inference; lihat Izin dan batasan.



Federation rule

Federation rule (fdrl_...) mengikat issuer ke akun layanan: JWT dari issuer yang memenuhi kondisi pencocokan rule dapat mencetak token yang bertindak sebagai target rule tersebut. workspace_id dalam permintaan create mengaktifkan rule di workspace tersebut saat pembuatan; tambahkan workspace lain nanti melalui sub-resource /federation_rules/{rule_id}/workspaces. Salah satu dari workspace_id atau applies_to_all_workspaces: true wajib ada saat create.

# Buat aturan (GitHub Actions melakukan deploy dari branch main)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "gha-deploy",
    "issuer_id": "fdis_...",
    "match": {
      "subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
      "claims": {"repository_owner": "my-org"}
    },
    "target": {
      "type": "service_account",
      "service_account_id": "svac_..."
    },
    "workspace_id": "wrkspc_...",
    "oauth_scope": "workspace:developer",
    "token_lifetime_seconds": 600
  }'

# Tampilkan daftar aturan, opsional difilter berdasarkan penerbit
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arsipkan aturan
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Endpoint list mengembalikan satu halaman rule dan cursor untuk halaman berikutnya:

{
  "data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
  "next_page": "..."
}

Untuk membaca atau memperbarui satu rule, gunakan GET dan POST pada /v1/organizations/federation_rules/{rule_id}. Untuk mengelola workspace tempat rule dapat mencetak token, gunakan GET dan POST pada /v1/organizations/federation_rules/{rule_id}/workspaces, dan DELETE pada /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.



Izin dan batasan

Rule dengan oauth_scope: org:admin harus menargetkan akun layanan dengan organization_role bernilai admin. Nama resource harus cocok dengan ^[a-z0-9-]+$, memiliki panjang 1 hingga 255 karakter, dan unik dalam satu organisasi untuk setiap tipe resource; untuk batasan lengkap di tingkat field, lihat Aturan validasi.



Paginasi dan pengarsipan

Endpoint list untuk akun layanan, federation issuer, dan federation rule menerima limit (1 hingga 100, default 20) dan cursor page yang diambil dari respons sebelumnya. Teruskan nilai next_page dari respons sebagai parameter query page pada permintaan berikutnya. List sub-resource rule-workspaces mengembalikan set lengkap tanpa paginasi. Resource yang diarsipkan disembunyikan dari list secara default; teruskan include_archived=true untuk menyertakannya.

Pengarsipan adalah soft delete dan bersifat idempoten: mengarsipkan resource yang sudah diarsipkan akan berhasil. Mengarsipkan issuer atau akun layanan mengembalikan 400 selama masih ada federation rule aktif yang mereferensikannya; arsipkan rule tersebut terlebih dahulu.



Lihat juga

• Workload Identity Federation: konsep dan panduan penyiapan di Console
• Referensi WIF: variabel lingkungan, aturan validasi, OAuth scope, dan kode error
• Admin API: bagian lain dari permukaan manajemen organisasi
• Referensi Admin API: skema permintaan dan respons yang dihasilkan untuk setiap endpoint Admin API