Mengelola WIF dengan Admin API

Admin API memungkinkan Anda membuat dan mengelola sumber daya Workload Identity Federation secara terprogram: service account, federation issuer, dan federation rule. Gunakan ini untuk menyimpan konfigurasi federasi Anda dalam infrastructure as code, menyediakannya 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 token bearer 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 mendapatkan token, dan keduanya membawa izin yang berbeda: token dari login Anda sendiri bertindak sebagai pengguna, sedangkan token terfederasi bertindak sebagai service account dan tidak dapat melakukan semua operasi di halaman ini.



Interaktif (terminal Anda)

Masuk dengan ant CLI di bawah profil khusus, dengan meminta scope org:admin (lihat Akses admin), lalu ekspor token bearer:

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 service account yang organization_role-nya adalah 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 sebuah 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 cakupan 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, service account, atau rule dengan wizard Connect workload, daftarkan mereka 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 service-account memerlukan header versi API dan token bearer:

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  -H "anthropic-version: 2023-06-01" \
  -H "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.



Service account

Sebuah service account (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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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

Endpoint create mengembalikan service account baru:

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

Untuk membaca atau memperbarui satu service account, gunakan GET dan POST pada /v1/organizations/service_accounts/{service_account_id}. Sebuah service account harus menjadi anggota workspace sebelum token terfederasi dapat bertindak di dalamnya. Setiap service account 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 Service accounts.



Federation issuer

Sebuah federation issuer (fdis_...) mendaftarkan penyedia identitas OIDC ke organisasi Anda. Field jwks adalah discriminated union yang mengontrol bagaimana Anthropic mengambil kunci penandatanganan penyedia:

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

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

# Mengarsipkan issuer
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "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 yang oauth_scope-nya selain workspace:developer atau workspace:inference; lihat Izin dan batasan.

Untuk detail parameter lengkap dan skema respons, lihat Referensi API Federation issuers.



Federation rule

Sebuah federation rule (fdrl_...) mengikat sebuah issuer ke sebuah service account: 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 lebih banyak workspace nanti melalui sub-resource /federation_rules/{rule_id}/workspaces. Salah satu dari workspace_id atau applies_to_all_workspaces: true diperlukan saat create.

# Membuat aturan (GitHub Actions melakukan deploy dari branch main)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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
  }'

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

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

Endpoint list mengembalikan satu halaman rule dan kursor 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 sebuah 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}.

Untuk detail parameter lengkap dan skema respons, lihat Referensi API Federation rules.



Izin dan batasan

Rule dengan oauth_scope: org:admin harus menargetkan service account yang organization_role-nya adalah admin. Nama sumber daya harus cocok dengan ^[a-z0-9-]+$, memiliki panjang 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 service-account, federation-issuer, dan federation-rule 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 list 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 service account 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