> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Create a vault">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="Append a credential">
    Add credentials to a Vault with nested `auth`:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Use in a Session">
    Reference Vaults via `vault_ids` when creating the Session:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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.

<Note>
  Use separate Vaults per environment (development vs. production) to avoid mixing credentials.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Start a session" icon="play" href="/cloud-agents/sessions">
    Run an agent against an environment.
  </Card>

  <Card title="Agent setup" icon="user-gear" href="/cloud-agents/define-agent">
    Review Agent configuration.
  </Card>

  <Card title="Build persistent memory" icon="brain" href="/cloud-agents/memory-stores">
    Give your agent persistent memory across sessions.
  </Card>

  <Card title="Cloud environment setup" icon="server" href="/cloud-agents/environments">
    Customize the runtime.
  </Card>
</CardGroup>