Autentikasi dengan vault

Vault dan kredensial adalah primitif autentikasi yang memungkinkan Anda mendaftarkan kredensial untuk layanan pihak ketiga satu kali dan mereferensikannya berdasarkan ID saat pembuatan sesi. Ini berarti Anda tidak perlu menjalankan penyimpanan rahasia sendiri, mengirimkan token pada setiap panggilan, atau kehilangan jejak pengguna akhir mana yang diwakili oleh agen saat bertindak.

Referensi vault adalah parameter per sesi, sehingga Anda dapat mengelola produk Anda pada granularitas sumber daya agent dan pengguna Anda pada granularitas sumber daya session.



Membuat vault

Vault adalah kumpulan credentials yang terkait dengan pengguna akhir. Berikan display_name dan secara opsional tandai dengan metadata agar Anda dapat memetakannya kembali ke catatan pengguna Anda sendiri.

VAULT_ID=$(ant beta:vaults create --transform id --raw-output < alice.vault.yaml)
echo "$VAULT_ID"  # "vlt_01ABC..."

display_name: Alice
metadata:
  external_user_id: usr_abc123

Responsnya adalah catatan vault lengkap:

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}



Menambahkan kredensial

Dua kategori kredensial didukung:

• Kredensial MCP (mcp_oauth, static_bearer): setiap kredensial dikunci oleh mcp_server_url. Ketika agen terhubung ke server pada URL tersebut saat runtime sesi, token diinjeksikan secara otomatis.
• Variabel lingkungan (environment_variable): setiap kredensial dikunci oleh secret_name (nama variabel lingkungan) dan disimpan di sandbox sebagai placeholder buram. Ketika agen memulai permintaan keluar, placeholder buram tersebut disubstitusi dengan rahasia sebenarnya saat egress. Agen tidak pernah melihat nilai rahasia tersebut. Gunakan ini untuk layanan apa pun yang mengautentikasi melalui variabel lingkungan, seperti CLI, SDK, atau panggilan API langsung.

Nilai kredensial aktual yang Anda berikan (token, access_token, refresh_token, client_secret, secret_value) diperlakukan sebagai field sensitif yang hanya dapat ditulis dan tidak pernah dikembalikan dalam respons API.

CREDENTIAL_ID=$(ant beta:vaults:credentials create \
  --vault-id "$VAULT_ID" \
  --display-name "Alice's Slack" \
  --transform id --raw-output <<'YAML'
auth:
  type: mcp_oauth
  mcp_server_url: https://mcp.slack.com/mcp
  access_token: xoxp-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    token_endpoint: https://slack.com/api/oauth.v2.access
    client_id: "1234567890.0987654321"
    scope: channels:read chat:write
    refresh_token: xoxe-1-...
    token_endpoint_auth:
      type: client_secret_post
      client_secret: abc123...
YAML
)

Kredensial disimpan sebagaimana diberikan dan tidak divalidasi hingga runtime sesi. Kredensial yang tidak valid muncul sebagai error autentikasi atau error downstream selama sesi, yang dipancarkan tetapi tidak memblokir sesi untuk melanjutkan.

Batasan:

• Kunci unik per vault. mcp_server_url (kredensial MCP) dan secret_name (kredensial variabel lingkungan) harus unik di antara kredensial aktif dalam sebuah vault. Membuat duplikat mengembalikan 409.
• Kunci bersifat immutable. Untuk mengubah mcp_server_url atau secret_name, arsipkan kredensial dan buat yang baru.
• Maksimum 20 kredensial per vault.



Mereferensikan vault saat pembuatan sesi

Teruskan vault_ids saat membuat sesi:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

Perilaku runtime:

• Ketika tidak ada kredensial MCP yang cocok berdasarkan mcp_server_url, koneksi dicoba tanpa autentikasi dan akan error jika server memerlukan autentikasi.
• Ketika beberapa vault berisi kredensial yang cocok, vault pertama dengan kecocokan yang menang.
• Dalam sesi multiagent, kredensial vault berlaku untuk setiap thread. Agen yang definisinya sendiri mendeklarasikan server MCP yang cocok akan mengautentikasi dengan kredensial ini. Lihat Menghubungkan agen ke server MCP.



Merotasi kredensial

Nilai rahasia, display_name, dan (pada kredensial variabel lingkungan) injection_location dapat diperbarui. Pembaruan injection_location digabungkan per field, seperti dijelaskan di tab Variabel lingkungan pada Menambahkan kredensial. Untuk sesi yang sedang berjalan, pembaruan injection_location dipropagasi dengan cara yang sama seperti rotasi rahasia: kredensial sesi diselesaikan ulang tanpa restart, seperti dijelaskan di Siklus hidup kredensial, dan lokasi yang diperbarui berlaku untuk permintaan keluar sesi berikutnya. Field struktural (mcp_server_url, secret_name, token_endpoint, client_id) dikunci setelah pembuatan. Untuk mengubahnya, arsipkan kredensial dan buat yang baru.

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'YAML'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
YAML



Siklus hidup kredensial

Kredensial diselesaikan ulang secara berkala, baik selama sesi maupun selama siklus hidup vault. Ini memastikan bahwa rotasi, pengarsipan, atau penghapusan kredensial dipropagasi ke sesi yang sedang berjalan tanpa restart.

Untuk mendapatkan notifikasi jika kredensial diarsipkan, dihapus, atau gagal di-refresh, Anda dapat berlangganan webhook vault dan kredensial yang terkait dengan perubahan siklus hidup tersebut.

Untuk kredensial mcp_oauth, penyelesaian ulang juga me-refresh access token jika telah kedaluwarsa. Jika refresh gagal, event vault_credential.refresh_failed dipancarkan.



Mendiagnosis kegagalan refresh OAuth

Untuk mendiagnosis mengapa refresh gagal, panggil POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (atau client.beta.vaults.credentials.mcp_oauth_validate(...) di SDK). Ini memungkinkan Anda memutuskan cara menangani kegagalan tersebut; tindakan yang tepat bergantung pada jenis error.

status tingkat atas memberi tahu Anda apa yang harus dilakukan selanjutnya:

• valid: token berfungsi; tidak ada tindakan yang diperlukan.
• invalid: grant telah hilang atau server OAuth menolak refresh dengan 4xx. Minta pengguna akhir untuk mengotorisasi ulang.
• unknown: error sementara (5xx, 429, atau kegagalan jaringan). Tunggu dan coba lagi.

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

Responsnya adalah objek vault_credential_validation. mcp_probe menyertakan langkah handshake MCP yang gagal; refresh menyertakan hasil dari refresh yang dicoba.

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



Operasi lainnya

• Mencantumkan vault atau kredensial: Dipaginasi, terbaru lebih dulu. Catatan yang diarsipkan dikecualikan secara default (teruskan include_archived=true untuk menyertakannya).
• Mengarsipkan vault: POST /v1/vaults/{id}/archive. Berlaku secara cascade ke semua kredensial. Rahasia dihapus; catatan dipertahankan untuk audit. Sesi mendatang yang mereferensikan vault ini gagal; sesi yang sedang berjalan tetap berlanjut.
• Mengarsipkan kredensial: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Menghapus payload rahasia; kunci kredensial (mcp_server_url atau secret_name) tetap terlihat dan dibebaskan untuk kredensial pengganti.
• Menghapus vault atau kredensial: Hard delete. Catatan tidak dipertahankan. Gunakan arsip jika Anda memerlukan jejak audit.