Mengelola WIF dengan Admin API

Admin API memungkinkan Anda membuat dan mengelola sumber daya Workload Identity Federation secara terprogram: akun layanan, penerbit federasi, dan aturan federasi. Gunakan API ini untuk menyimpan konfigurasi federasi Anda sebagai "infrastructure as code" (infrastruktur sebagai kode), menyediakannya dari CI, dan mereproduksinya di berbagai organisasi alih-alih mengklik satu per satu di Claude Console. Endpoint ini berbagi awalan path /v1/organizations dengan bagian lain dari Admin API.

Prasyarat

Setiap permintaan di halaman ini diautentikasi dengan "bearer token" (token pembawa) OAuth 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: setiap pengikatan workspace diabaikan. Ada dua cara untuk memperoleh 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 di bawah profil khusus, dengan meminta scope org:admin (lihat Akses admin), lalu ekspor bearer token. Login dengan --profile admin menyimpan kredensial org:admin di bawah nama profilnya sendiri dan juga menjadikannya profil aktif CLI, dan variabel yang diekspor berlaku untuk setiap panggilan SDK dan CLI di shell tersebut; jadi gunakan shell yang Anda khususkan untuk administrasi, hapus variabel tersebut setelah selesai, dan alihkan CLI kembali dengan ant profile activate default:

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

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

SDK dan CLI ant membaca ANTHROPIC_AUTH_TOKEN secara otomatis; biarkan ANTHROPIC_API_KEY tidak diatur di shell yang sama, karena endpoint ini menolak kunci API dan setiap klien menggunakan kunci tersebut ketika keduanya diatur.

Workload (CI dan otomatisasi)

Buat aturan federasi dengan oauth_scope: org:admin yang menargetkan akun layanan yang organization_role-nya adalah admin. Aturan 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 menjelaskan penyiapan satu kali per organisasi ini.

Bootstrap workload untuk mengelola WIF

Satu aturan 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 penerbit federasi dan setiap aturan federasi berlingkup workspace melalui API ini.

1. 1

   Buat aturan org:admin di Console

   Di Claude Console, buka halaman Workload identity (platform.claude.com/settings/workload-identity-federation) dan pilih Connect workload untuk membuat satu aturan federasi bagi workload otomatisasi Anda, misalnya workflow GitHub Actions di repositori infrastruktur Anda. Di bawah Advanced rule options, atur scope OAuth aturan ke org:admin: wizard kemudian membuat akun layanan baru dengan peran organisasi Admin (atau meminta Anda memilih akun layanan admin yang sudah ada sebagai target).

2. 2

   Tukarkan token identitas workload

   Workload yang menggunakan salah satu SDK atau CLI ant tidak melakukan pertukaran itu sendiri. Arahkan klien ke aturan dengan variabel lingkungan federasi dan buat klien tanpa argumen, persis seperti untuk inferensi di Membuat klien SDK; klien menukarkan token identitas pada permintaan pertama dan, sebelum token akses yang dihasilkan kedaluwarsa, membaca ulang token identitas dan menukarkannya lagi:

   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...        # the org:admin rule from step 1
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
   export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...       # the rule's target service account
   export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt  # or ANTHROPIC_IDENTITY_TOKEN
   # ANTHROPIC_WORKSPACE_ID hanya diperlukan jika aturan diaktifkan untuk semua
   # workspace atau lebih dari satu; endpoint org:admin mengabaikan binding tersebut.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   CLI ant membaca variabel yang sama, atau menerima flag --federation-rule, --organization-id, --service-account-id, dan --identity-token-file. Untuk workload yang menjalankan lebih dari satu perintah ant, gunakan profil federasi alih-alih flag atau variabel lingkungan: dengan flag atau variabel, CLI menukarkan token identitas lagi di setiap proses, dan token identitas yang membawa klaim jti (token GitHub Actions membawanya) hanya diterima sekali, sehingga perintah kedua akan ditolak; profil juga merupakan satu-satunya cara untuk memberikan workspace_id kepada CLI untuk pertukaran ketika aturan diaktifkan untuk semua workspace atau lebih dari satu, karena tidak seperti SDK, CLI tidak meneruskan ANTHROPIC_WORKSPACE_ID atau --workspace-id ke dalam pertukaran. Setiap SDK juga menerima pengaturan yang sama sebagai argumen konstruktor eksplisit, yang ditunjukkan per bahasa di Membuat klien SDK. Lihat Variabel lingkungan dan Prioritas kredensial untuk daftar lengkap dan urutannya.

   Workload yang memanggil API dengan curl menukarkan JWT dengan bearer token org:admin berumur pendek secara mandiri, menggunakan pertukaran token yang sama seperti workload terfederasi lainnya, dan mengirimkannya di header authorization: Bearer.

3. 3

   Kelola penerbit dan aturan berlingkup workspace melalui API

   Dengan klien yang telah dikonfigurasi (atau, untuk curl, token yang dicetak di ANTHROPIC_AUTH_TOKEN), workload membuat dan mengelola konfigurasi federasi Anda menggunakan endpoint di halaman ini.

Untuk operasi yang dapat dan tidak dapat dilakukan oleh token yang dicetak workload, lihat Izin dan batasan. Jika Anda sudah membuat penerbit, akun layanan, atau aturan dengan wizard Connect workload, tampilkan daftarnya dengan endpoint berikut dan impor ke 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:

Di SDK, endpoint ini adalah client.organization.service_accounts, client.organization.federation.issuers, dan client.organization.federation.rules (ant organization:service-accounts, federation:issuers, dan federation:rules di CLI). Contoh SDK dan CLI membuat klien default, yang mengirimkan bearer token dari ANTHROPIC_AUTH_TOKEN, atau, dalam workload otomatis, melakukan pertukaran federasi sendiri seperti yang dijelaskan di Bootstrap workload untuk mengelola WIF. Metode list SDK mengambil halaman berikutnya sesuai permintaan, sehingga limit mengatur ukuran halaman; contoh PHP dan Ruby membaca satu halaman.

client = anthropic.Anthropic()

service_accounts = client.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

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 diperankan oleh token terfederasi. Atur organization_role ke developer.

Buat akun layanan:

client = anthropic.Anthropic()

service_account = client.organization.service_accounts.create(
    name="inference-worker", organization_role="developer"
)

print(f"id: {service_account.id}")
print(f"name: {service_account.name}")

Tampilkan daftar akun layanan:

client = anthropic.Anthropic()

service_accounts = client.organization.service_accounts.list(limit=20)

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Arsipkan akun layanan:

client = anthropic.Anthropic()

service_account = client.organization.service_accounts.archive(
    "svac_01ABCDEFabcdef0123456789XY"
)

print(f"id: {service_account.id}")
print(f"archived_at: {service_account.archived_at}")

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}.

Untuk detail parameter lengkap dan skema respons, lihat Referensi API akun layanan.

Penerbit federasi

Penerbit federasi (fdis_...) mendaftarkan penyedia identitas OIDC ke organisasi Anda. Field jwks adalah "discriminated union" (union terdiskriminasi) yang mengontrol cara Anthropic mengambil kunci penandatanganan penyedia:

Daftarkan penerbit. Contoh ini mendaftarkan GitHub Actions dengan penemuan JWKS:

client = anthropic.Anthropic()

issuer = client.organization.federation.issuers.create(
    name="github-actions",
    issuer_url="https://token.actions.githubusercontent.com",
    jwks={"type": "discovery"},
)

print(f"id: {issuer.id}")
print(f"name: {issuer.name}")
print(f"issuer_url: {issuer.issuer_url}")

Tampilkan daftar penerbit:

client = anthropic.Anthropic()

issuers = client.organization.federation.issuers.list(limit=20)

for issuer in issuers:
    print(f"{issuer.id}: {issuer.name}")

Arsipkan penerbit:

client = anthropic.Anthropic()

issuer = client.organization.federation.issuers.archive(
    "fdis_01ABCDEFabcdef0123456789XY"
)

print(f"id: {issuer.id}")
print(f"archived_at: {issuer.archived_at}")

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

Untuk detail parameter lengkap dan skema respons, lihat Referensi API penerbit federasi.

Aturan federasi

Aturan federasi (fdrl_...) mengikat penerbit ke akun layanan: JWT dari penerbit yang memenuhi kondisi pencocokan aturan dapat mencetak token yang bertindak sebagai target aturan. workspace_id dalam permintaan create mengaktifkan aturan 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 diisi saat create.

Buat aturan. Contoh ini memungkinkan deploy GitHub Actions dari branch main bertindak sebagai akun layanan:

client = anthropic.Anthropic()

rule = client.organization.federation.rules.create(
    name="gha-deploy",
    issuer_id="fdis_01ABCDEFabcdef0123456789XY",
    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_01ABCDEFabcdef0123456789XY",
    },
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    oauth_scope="workspace:developer",
    token_lifetime_seconds=600,
)

print(f"id: {rule.id}")
print(f"name: {rule.name}")

Tampilkan daftar aturan, secara opsional difilter berdasarkan penerbit:

client = anthropic.Anthropic()

rules = client.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

for rule in rules:
    print(f"{rule.id}: {rule.name}")

Arsipkan aturan:

client = anthropic.Anthropic()

rule = client.organization.federation.rules.archive("fdrl_01ABCDEFabcdef0123456789XY")

print(f"id: {rule.id}")
print(f"archived_at: {rule.archived_at}")

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

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

Untuk membaca atau memperbarui satu aturan, gunakan GET dan POST pada /v1/organizations/federation_rules/{rule_id}. Untuk mengelola workspace tempat aturan 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}.

Untuk detail parameter lengkap dan skema respons, lihat Referensi API aturan federasi.

Izin dan batasan

Aturan dengan oauth_scope: org:admin harus menargetkan akun layanan yang organization_role-nya adalah admin. Nama sumber daya harus cocok dengan ^[a-z0-9-]+$, terdiri dari 1 hingga 255 karakter, dan unik dalam satu organisasi untuk setiap jenis sumber daya; untuk batasan tingkat field selengkapnya, lihat Aturan validasi.

Paginasi dan pengarsipan

Endpoint list akun layanan, penerbit federasi, dan aturan federasi 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. Sumber daya yang diarsipkan disembunyikan dari daftar secara default; teruskan include_archived=true untuk menyertakannya.

Pengarsipan adalah "soft delete" (penghapusan lunak) dan bersifat idempoten: mengarsipkan sumber daya yang sudah diarsipkan akan berhasil. Mengarsipkan penerbit atau akun layanan mengembalikan 400 selama aturan federasi yang aktif masih mereferensikannya; arsipkan aturan tersebut terlebih dahulu.

Lihat juga

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