Authenticate with Vaults

Store credentials in your deployment and make them available to Agent Sessions without hard-coding secrets.

Agents often need to access third-party services — GitHub, Jira, databases, or custom remote MCP servers. Vaults provide secure credential storage so you can store tokens in your own AstraBox deployment and use them in 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 service URL or environment variable name
`auth.type`	Credential auth type: Bearer token for an MCP service (`static_bearer`), OAuth token for an MCP service (`mcp_oauth`), API-key header for an MCP service (`mcp_static_header`), HTTP Basic for an HTTPS destination (`http_basic`), or Environment variable for another service (`environment_variable`)
`vault_ids`	The ordered list of Vault IDs assigned to an Agent or Assistant

Who manages credentials

Vaults and Credentials are managed by platform administrators. This covers listing and creating records, updating or rotating secrets, archiving and deleting records, and assigning or unassigning Vaults. All of these API routes are under /api/v1/admin/; a signed-in user without the administrator role receives 403 ADMIN_ROLE_REQUIRED.

Creating an Agent does not grant credential-management permission. Agent developers who are not administrators ask their platform administrator to configure the required credential and assign its Vault to the Agent. Users can then run an Agent with its assigned credentials without choosing a Vault or entering a token for each Session. This applies to every credential type, including MCP tokens, OAuth tokens, Git HTTP Basic, and environment variables.

Security

access_token is never returned in API responses.
Other secrets such as token, password, refresh_token, and client_secret are also never returned.
Credentials are encrypted at rest.
Credentials are available only to assigned workloads. Agent preparation also uses assigned HTTP Basic credentials to download private Skills and Plugins before a Session exists.
Only an administrator assigns a Vault to an Agent or Assistant. Whoever authors the Agent chooses which MCP URLs it calls, but a Credential is attached only to requests for the destination it is bound to. An Agent's own MCP server definition cannot set provider or credential_target_url: those fields select the platform's gateway credential or point a Credential at another URL, and only an administrator's MCP catalog assignment sets them. A definition that sets either is refused with AGENT_MCP_FIELD_RESERVED (403).
Repository deploy keys are deployment secrets, not Vault Credentials. An Agent can name only the ones an administrator lists; see Access GitHub.

End-to-end flow

1. Create a Vault

Create Vaults in Console → Credentials, or use the administration API:

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

Example response:

{
  "code": "OK",
  "message": "success",
  "data": {
    "vault_id": "vlt_8a15f9c8d1d34cf4b7b485d735c77d75",
    "display_name": "My GitHub credentials",
    "metadata": {},
    "archived_at": null,
    "created_at": "2026-08-24T08:00:00Z",
    "updated_at": "2026-08-24T08:00:00Z"
  }
}

2. Add a Credential

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

A target can receive multiple Vaults. The Session uses the current assignment at creation time. Removing an assignment stops later Sessions from receiving that Vault. The platform automatically admits the exact destination hosts named by active outbound credential bindings. Those hosts are already part of the effective sandbox policy, so the RuntimeProfile allowlist needs no duplicate entries.

curl -X POST \
  https://astrabox.example.com/api/v1/admin/vaults/vlt_8a15f9c8d1d34cf4b7b485d735c77d75/credentials \
  -H "Authorization: Bearer $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 credential_id and a sanitized auth object. It does not include secret values.

For MCP OAuth, import the access token and optional refresh configuration:

curl -X POST \
  https://astrabox.example.com/api/v1/admin/vaults/vlt_8a15f9c8d1d34cf4b7b485d735c77d75/credentials \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "mcp_oauth",
      "mcp_server_url": "https://mcp.linear.app/mcp",
      "access_token": "access_token_xxxxxxxx",
      "expires_at": "2026-08-24T09:00:00Z",
      "refresh": {
        "token_endpoint": "https://api.linear.app/oauth/token",
        "client_id": "astrabox",
        "auth_method": "none",
        "refresh_token": "refresh_token_xxxxxxxx"
      }
    }
  }'

AstraBox does not run the browser authorization flow. Obtain the token from the remote MCP service, then store it in the Vault. When the Credential contains a valid refresh configuration, AstraBox refreshes an expired access token when preparing or reconnecting the runtime and before it hands the Agent program each message. It does not check token expiry before every individual MCP HTTP request.

For a service that uses a custom request header, use mcp_static_header. To make another service credential available as an environment variable, use environment_variable; see Protect credentials used by Agents for its host and request restrictions, and for header delivery, which replaces the placeholder only in one named request header.

Private Git repositories for Plugins and Skills

For a Plugin or Skill downloaded from a private HTTPS Git repository, an administrator configures access in the console:

Open Console → Credentials, create a Vault, and open it.
Click Add credential, choose HTTP Basic (Git HTTPS), fill in the destination URL, username, and password or access token, then save.
In the Vault's assignments, click Assign, choose Agent, and select the Agent that downloads the Plugin or Skill. Saving a credential alone does not assign it to an Agent.
Keep the clean repository URL in the Agent's Plugin or Skill configuration and start a new Session after the Vault has been assigned.

For example, to download a private Gitee repository:

Console field	Value
Credential type	HTTP Basic (Git HTTPS) (`http_basic`)
Destination URL	`https://gitee.com/your-team/private-plugins.git` — replace with the repository's actual HTTPS clone URL
Username	The Gitee username of the account with access to the repository
Password or access token	That account's personal access token with permission to read the repository

Gitee's HTTPS instructions describe using the account username and a personal access token in place of a login password. Use the username and token permissions required by your Git host. For a Skill source such as https://gitee.com/your-team/private-skills.git@main#skills/review, the credential destination is only https://gitee.com/your-team/private-skills.git; keep the revision and subdirectory in the Skill configuration.

The equivalent administration API request is:

POST /api/v1/admin/vaults/{vault_id}/credentials
Content-Type: application/json

{
  "display_name": "Private Skill repository",
  "auth": {
    "type": "http_basic",
    "url": "https://gitee.com/your-team/private-skills.git",
    "username": "your-gitee-username",
    "password": "<repository-access-token>"
  }
}

Use the username required by the Git host and a token with the repository permissions the operation needs. The type describes the authentication method, not a Git vendor. password is write-only; the response includes only the type, destination URL, and username. The URL must be HTTPS on port 443 with a non-root path, without embedded credentials, query, fragment, or wildcard patterns.

Assign the Vault to the Agent and keep the Skill or Plugin Git URL free of credentials. AstraBox supplies the binding before downloading those sources. OpenSandbox adds HTTP Basic authentication to GET, HEAD, and POST requests for the configured path and its descendants, not sibling repository paths. No token or placeholder needs to be placed in the Git URL or sandbox environment. This uses the same platform path for every Agent program and for custom Git Skill sources and those selected from an extension catalog.

3. Use in a Session

Assign the Vault to an Agent or Assistant in Console → Credentials, or set the ordered vault_ids through the administration API:

curl -X PUT \
  https://astrabox.example.com/api/v1/admin/agents/agent_xxx/credential-vaults \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_ids": ["vlt_8a15f9c8d1d34cf4b7b485d735c77d75"]
  }'

New Sessions created from that Agent automatically gain access to every active Credential in the Vault. For MCP credentials, the first Vault with a matching MCP server URL wins. HTTP Basic credentials likewise use the first Vault with a matching destination URL. An Assistant can use MCP credentials, but it cannot be assigned a Vault containing environment_variable or http_basic credentials.

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`, `mcp_static_header`, `http_basic`, or `environment_variable`
`auth.mcp_server_url`	string	Yes for MCP credentials	Remote 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.header_name`	string	Yes for `mcp_static_header`, and for `environment_variable` with `delivery: "header"`	Custom request-header name
`auth.value`	string	Yes for `mcp_static_header`	Custom request-header value; write-only
`auth.url`	string	Yes for `http_basic`	Clean HTTPS destination URL with a non-root path
`auth.username`	string	Yes for `http_basic`	HTTP Basic username; no colon or control characters
`auth.password`	string	Yes for `http_basic`	Password or access token; write-only
`auth.secret_name`	string	Yes for `environment_variable`	Environment variable name
`auth.secret_value`	string	Yes for `environment_variable`	Secret value; write-only
`auth.delivery`	string	No	`environment_variable` only: `substitution` (default) or `header`; see header delivery
`auth.expires_at`	string	No	OAuth access-token expiration time in RFC 3339 format
`auth.refresh`	object	No	OAuth refresh configuration

FAQ

Q: A Plugin or Skill clone fails with could not read Username for 'https://gitee.com': No such device or address. What should I check?

A: Git could not complete authentication and tried to prompt for credentials in a runtime without interactive input. The message alone does not establish whether the credential is missing, rejected, or scoped to another repository. Ask the administrator to check:

The Vault contains an active HTTP Basic (Git HTTPS) credential. An MCP Bearer token or environment-variable credential does not configure Git HTTP Basic authentication.
Its destination matches the actual HTTPS clone URL, including the repository path and any .git suffix. A host-only URL is insufficient; Skill @ref and #path suffixes do not belong in this field.
The username is correct, the token is valid, and its account and permissions allow reading this repository. Also verify the repository URL itself.
The Vault is active and assigned to the Agent that failed. Start a new Session after correcting the configuration.

Keep the token in the Credential's password field; do not put it in the Git URL, Agent prompt, or error report. See the configuration steps.

Q: What happens when an MCP OAuth token expires? A: If the Credential has a refresh token and refresh configuration, AstraBox refreshes an expired token during runtime preparation or reconnect and before it hands the Agent program the next message. When several conversations or server replicas find the token expired at the same time, one of them refreshes it and the others use the new token, so a provider that rotates refresh tokens on every use keeps accepting the Credential. If refresh is unavailable or no longer valid, rotate the Credential.

Q: Can I update a Credential's token? A: Yes. A PATCH request rotates the supplied write-only secret fields. The credential type, MCP server URL, custom header name, HTTP Basic destination URL and username, environment variable name and delivery, OAuth token endpoint, and OAuth client ID are immutable; archive the Credential and create a new one to change them.

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 rotate, archive, or delete them.

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

Next steps

Sessions — Run an Agent with its assigned Vaults.
Defining an Agent — Assign the RuntimeProfile and extensions that use credentials.
Protect credentials used by Agents — Configure protected delivery and outbound restrictions.
RuntimeProfiles — Configure the runtime and its network access.

Core concepts​

Who manages credentials​

Security​

End-to-end flow​

1. Create a Vault​

2. Add a Credential​

Private Git repositories for Plugins and Skills​

3. Use in a Session​

Parameters​

FAQ​

Next steps​