Authenticate with vaults

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` or `mcp_oauth`
`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, and client_secret are also never returned.
Credentials are encrypted at rest.
Only the linked Sessions can read credential contents at runtime.

End-to-end flow

Create a vault

curl -X POST https://api.qoder.com/api/v1/cloud/vaults \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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"
}

Add a credential

For a static Bearer token, add a Credential with nested auth:

curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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.For MCP OAuth, use the browser authorization flow:

curl -X POST https://api.qoder.com/api/v1/cloud/oauth/start \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
    "mcp_server_url": "https://mcp.linear.app/mcp",
    "client_id": "",
    "client_secret": ""
  }'

Open the returned authorization_url. After the provider redirects to the CAS callback, CAS exchanges the code and creates an mcp_oauth Credential in the Vault. See Start MCP OAuth for PKCE, client registration, and callback behavior.If you already hold an OAuth access token and refresh configuration, you can instead import them through Create a credential.

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_ACCESS_TOKEN" \
  -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` or `mcp_oauth`
`auth.mcp_server_url`	string	Yes for MCP credentials	MCP server URL
`auth.token`	string	Yes for `static_bearer`	Bearer token value; write-only
`auth.access_token`	string	Yes when importing `mcp_oauth`	OAuth access token; write-only
`auth.expires_at`	string	No	OAuth access-token expiration time in RFC 3339 format
`auth.refresh`	object	No	OAuth refresh configuration; see Vault schemas

FAQ

Q: What happens when an MCP OAuth token expires? A: If the provider returned a refresh token, CAS refreshes the credential when needed before MCP discovery or execution. If refresh is unavailable or no longer valid, run the OAuth authorization flow again. Q: Can I update a Credential's token? A: Yes. Rotate secrets in place with Update a credential, then confirm an MCP OAuth credential with Validate an MCP OAuth credential. 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.

​Core concepts

​Security

​End-to-end flow

​Parameters

​FAQ

​Next steps

Start a session

Agent setup

Build persistent memory

Cloud environment setup

Core concepts

Security

End-to-end flow

Parameters

FAQ

Next steps