Mengelola WIF dengan Admin API

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

Prasyarat

Setiap permintaan di halaman ini diautentikasi dengan bearer token 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: pengikatan workspace apa pun 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 (unset) ketika Anda selesai, dan kembalikan CLI 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 tersebut memperbarui token secara otomatis).

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

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 oleh otomatisasi untuk dirinya sendiri. Bagian berikutnya memandu Anda melalui penyiapan sekali-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 issuer federasi dan setiap aturan federasi dengan scope workspace melalui API ini.

1. 1

   Buat aturan org:admin di Console

   Di Claude Console, buka Settings → Workload identity dan pilih Connect workload untuk membuat satu aturan federasi bagi workload otomatisasi Anda, misalnya alur kerja GitHub Actions di repositori infrastruktur Anda. Di bawah Advanced rule options, setel OAuth scope 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 penukaran 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 access token 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 pengikatan ini.
   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 penukaran 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 penukaran. Setiap SDK juga menerima pengaturan yang sama sebagai argumen konstruktor eksplisit, yang ditampilkan per bahasa di Membuat klien SDK. Lihat Variabel lingkungan dan Prioritas kredensial untuk daftar lengkap dan urutannya.

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

3. 3

   Kelola issuer dan aturan dengan scope workspace melalui API

   Dengan klien yang telah dikonfigurasi (atau, untuk curl, token yang telah 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 issuer, akun layanan, atau aturan 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:

Di SDK, endpoint ini adalah client.beta.organization.service_accounts, client.beta.organization.federation.issuers, dan client.beta.organization.federation.rules (ant beta: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 penukaran federasi sendiri seperti yang dijelaskan di Bootstrap workload untuk mengelola WIF. Metode list SDK mengambil halaman selanjutnya sesuai permintaan, sehingga limit menetapkan ukuran halaman; contoh PHP dan Ruby membaca satu halaman.

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list()

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

Kunci Admin API tidak diterima di 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. Setel organization_role ke developer.

Buat akun layanan:

client = anthropic.Anthropic()

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

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

Daftarkan akun layanan:

client = anthropic.Anthropic()

service_accounts = client.beta.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.beta.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 sebuah 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.

Issuer federasi

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

Daftarkan issuer. Contoh ini mendaftarkan GitHub Actions dengan JWKS discovery:

client = anthropic.Anthropic()

issuer = client.beta.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}")

Daftarkan issuer yang ada:

client = anthropic.Anthropic()

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

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

Arsipkan issuer:

client = anthropic.Anthropic()

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

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

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 aturan yang oauth_scope-nya selain workspace:developer atau workspace:inference; lihat Izin dan batasan.

Untuk detail parameter lengkap dan skema respons, lihat referensi API Issuer federasi.

Aturan federasi

Aturan federasi (fdrl_...) mengikat issuer ke akun layanan: JWT dari issuer yang memenuhi kondisi pencocokan aturan dapat mencetak token yang bertindak sebagai target aturan tersebut. workspace_id dalam permintaan create mengaktifkan aturan di workspace tersebut saat pembuatan; tambahkan lebih banyak workspace 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. Contoh ini memungkinkan deploy GitHub Actions dari branch main bertindak sebagai akun layanan:

client = anthropic.Anthropic()

rule = client.beta.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}")

Daftarkan aturan, dengan filter opsional berdasarkan issuer:

client = anthropic.Anthropic()

rules = client.beta.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.beta.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 kursor 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 lengkap tingkat field, lihat Aturan validasi.

Paginasi dan pengarsipan

Endpoint list akun layanan, issuer federasi, dan aturan federasi menerima limit (1 hingga 100, default 20) dan kursor 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 dan bersifat idempoten: mengarsipkan sumber daya yang sudah diarsipkan akan berhasil. Mengarsipkan issuer atau akun layanan mengembalikan 400 selama aturan federasi aktif masih mereferensikannya; arsipkan aturannya 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