Authenticate with vaults

Store and inject secrets safely into agent sessions.

Agents often need to access third-party services — GitHub, Jira, databases, or custom MCP servers. Vaults provide secure credential storage so you can hand tokens to us and have them injected into Sessions on demand without hard-coding secrets in your code.

Core concepts

Concept	Description
Vault	A credential container that can hold multiple Credentials
Credential	A single credential bound to a specific MCP server URL
auth.type	Credential auth type: static_bearer, mcp_oauth, or environment_variable
vault_ids	The list of Vault IDs referenced when creating a Session

Security

• access_token is never returned in API responses.
• Other secrets such as token, refresh_token, client_secret, and secret_value are also never returned.
• Credentials are encrypted at rest.
• Only the linked Sessions can read credential contents at runtime.

End-to-end flow

1. Create a vault

   curl -X POST https://api.qoder.com/api/v1/cloud/vaults \
     -H "Authorization: Bearer $QODER_PAT" \
     -H "Content-Type: application/json" \
     -d '{
       "display_name": "My GitHub credentials",
       "metadata": {}
     }'
   

   Example response:

   {
     "id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
     "type": "vault",
     "display_name": "My GitHub credentials",
     "credentials": [],
     "metadata": {},
     "archived_at": null,
     "created_at": "2026-05-18T08:00:00Z",
     "updated_at": "2026-05-18T08:00:00Z"
   }
   
2. Append a credential

   Add credentials to a Vault with nested auth:

   curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
     -H "Authorization: Bearer $QODER_PAT" \
     -H "Content-Type: application/json" \
     -d '{
       "auth": {
         "type": "static_bearer",
         "mcp_server_url": "https://jira.example.com/mcp",
         "token": "jira_token_xxxxxxxx"
       }
     }'
   

   The response returns type: "vault_credential" and a sanitized auth object. It does not include secret values.

3. Use in a Session

   Reference Vaults via vault_ids when creating the Session:

   curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
     -H "Authorization: Bearer $QODER_PAT" \
     -H "Content-Type: application/json" \
     -d '{
       "agent": "agent_xxx",
       "vault_ids": ["vault_019e5cdb9c3f71c3b6505eba937a40b4"]
     }'
   

   At runtime, the Agent automatically gains access to every Credential in the Vault to authenticate to the corresponding MCP servers.

Parameters

Parameter	Type	Required	Description
display_name	string	Yes	Display name for the Vault
metadata	object	No	Custom metadata
auth.type	string	Yes for credentials	static_bearer, mcp_oauth, or environment_variable
auth.mcp_server_url	string	Yes for MCP credentials	MCP server URL
auth.token	string	Yes for static_bearer	Bearer token value; write-only

FAQ

Q: Can I update a Credential’s token? A: Rotate by deleting the old Credential and creating a new one.

Q: How many Vaults can a Session reference? A: There’s no hard limit, but group by service for clarity.

Q: My token leaked. What now? A: Delete the Credential immediately, revoke the token in the third-party platform, and create a new Credential.

Q: Can I read stored tokens? A: No. For security, credential secrets are write-only — you can only delete and recreate.

Use separate Vaults per environment (development vs. production) to avoid mixing credentials.

Next steps

Start a session

Run an agent against an environment.

Agent setup

Review Agent configuration.

Build persistent memory

Give your agent persistent memory across sessions.

Cloud environment setup

Customize the runtime.