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 (secret store) Anda 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 resource agent dan pengguna Anda pada granularitas resource session.

Membuat vault

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

vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(vault.id)  # "vlt_01ABC..."

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 berdasarkan 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 berdasarkan secret_name (nama variabel lingkungan) dan disimpan di sandbox sebagai placeholder buram (opaque placeholder). Ketika agen memulai permintaan keluar, placeholder buram tersebut diganti dengan rahasia yang sebenarnya saat egress. Agen tidak pernah melihat nilai rahasia. Gunakan ini untuk layanan apa pun yang melakukan autentikasi 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 (write-only) dan tidak pernah dikembalikan dalam respons API.

credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    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.user.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)

bearer_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Linear API key",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://mcp.linear.app/mcp",
        "token": "lin_api_your_linear_key",
    },
)

env_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Notion API key for sandbox",
    auth={
        "type": "environment_variable",
        "secret_name": "NOTION_API_KEY",
        "secret_value": "ntn_your-secret-here",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.notion.com"],
        },
        "injection_location": {"header": True},
    },
)
if env_credential.auth.type == "environment_variable":
    location = env_credential.auth.injection_location
    print(f"header: {location.header}, body: {location.body}")  # header: True, body: False

Kredensial disimpan sebagaimana diberikan dan tidak divalidasi hingga runtime sesi. Kredensial yang tidak valid muncul sebagai error autentikasi atau error hilir selama sesi, yang dipancarkan tetapi tidak menghalangi sesi untuk berlanjut.

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 tidak dapat diubah. Untuk mengubah mcp_server_url atau secret_name, arsipkan kredensial dan buat yang baru.
• Maksimum 20 kredensial per vault.

Mereferensikan vault saat pembuatan sesi

Berikan vault_ids saat membuat sesi:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

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 yang memiliki kecocokan yang digunakan.
• Dalam sesi multiagen, kredensial vault berlaku untuk setiap thread. Agen yang definisinya sendiri mendeklarasikan server MCP yang cocok akan melakukan autentikasi 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 dipropagasikan 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.

client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)

Siklus hidup kredensial

Kredensial diselesaikan ulang secara berkala, baik selama sesi maupun selama siklus hidup vault. Ini memastikan bahwa rotasi, pengarsipan, atau penghapusan kredensial dipropagasikan 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 sudah 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 perlu tindakan.
• invalid: grant sudah hilang atau server OAuth menolak refresh dengan 4xx. Minta pengguna akhir untuk melakukan otorisasi ulang.
• unknown: error sementara (5xx, 429, atau kegagalan jaringan). Tunggu dan coba lagi.

validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "valid", "invalid", or "unknown"

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

{
  "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

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