Agent Grants: Scoped, Time-Limited Credential Access

Token Vault provides scoped, time-limited credential access for AI agents, external scripts, and ADK agents.

Loading diagram...

Creating an Agent

Go to the Agents tab and click "Create Agent".
Give it a name (e.g., "Claude Code") and optional description.
Copy the generated API key (tvagent_...). It is shown only once.

Fill in the agent name and description in the create dialog:

Create Agent dialog with fields filled

After clicking "Create Agent", the success screen shows your API key. Copy it immediately - it cannot be retrieved later:

Agent Created success with API key

Granting Credentials

Open the agent's detail page and click "Grant".
Select which vault token the agent can access.
Set an expiry (1 hour to 30 days, or "Until revoked").
Optionally enable auto-refresh for OAuth tokens.

Webhook Mode: Zero-Knowledge Grants

In Webhook Mode, grants can be created without Token Vault verifying credential presence. Your webhook owns the storage and Token Vault trusts it to hold the credential. Token Vault never accesses the credential during grant creation.

The grant dialog lets you pick a credential and set the access window:

Grant Credential dialog

Agent Credential Retrieval

Your agent calls the HTTP endpoint with its API key:

# Get a specific credential
GET /api/agents/credentials?service=github
Authorization: Bearer tvagent_abc123...

# List all available grants
GET /api/agents/credentials
Authorization: Bearer tvagent_abc123...

Auth can also be passed via x-agent-key header or ?key= query param.

Zero-Knowledge Redirect (Webhook Mode)

In Webhook Mode, Token Vault never sees your plaintext credentials, not even during agent access. When an agent requests a credential:

Loading diagram...

The agent sends GET /api/agents/credentials?service=github to Token Vault.
Token Vault validates the agent's API key, checks the grant, and evaluates ABAC policies.
Token Vault generates a signed credential ticket (HMAC-SHA256) and returns a 307 redirect to your webhook's /v1/credential endpoint.
The agent's HTTP client follows the redirect and receives the credential directly from your webhook.
Your webhook verifies the ticket signature, decrypts the credential, and returns it.

Token Vault acts as a policy gate: it decides whether the agent can access the credential, but never touches the credential itself. The Authorization header is stripped on cross-domain redirects, so your webhook authenticates via the signed ticket, not the agent key.

Platform Mode

In Platform Mode, there is no redirect. Token Vault decrypts the credential and returns it directly to the agent.

Revocation

Loading diagram...

Grant Expiry & Revocation

Grants expire automatically after the set duration. You can also revoke any grant immediately from the agent's detail page. The agent will get an error on its next request.

MCP Service Endpoint

Agents with MCP enabled can connect as a native MCP server using the standard Streamable HTTP transport. This lets AI agents use tools/call to list and retrieve credentials via JSON-RPC -- no custom HTTP integration needed.

Loading diagram...

Connecting via MCP

Add Token Vault as an MCP server in your agent's config. The agent authenticates with its tvagent_ API key:

MCP config (e.g., claude_desktop_config.json)

{
  "mcpServers": {
    "tokenvault": {
      "url": "https://api.tokenvault.uk/api/agents/mcp",
      "headers": {
        "Authorization": "Bearer tvagent_abc123..."
      }
    }
  }
}

Enable MCP access for the agent in the agent detail page (toggle "MCP Enabled").

Available MCP Tools

`list_credentials`

Lists all credentials the agent has been granted access to. Returns service names, expiry times, and refresh policies. Takes no parameters.

// Request
{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_credentials",
    "arguments": {}
  }
}

// Response
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "Available credentials (2):\n  - github (expires: Never, refresh: none)\n  - google (expires: 2025-02-20T12:00:00+00:00, refresh: auto)"
    }]
  }
}

`get_credential`

Retrieves an access token for a specific service. The agent must have an active grant.

// Request
{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_credential",
    "arguments": { "service": "github" }
  }
}

// Response
{
  "jsonrpc": "2.0", "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "Access token for github:\nghp_abc123...\n\nToken type: pat\nScope: repo,read:org\nGrant expires: Never"
    }]
  }
}

Webhook Mode: Zero-Knowledge MCP

In Webhook Mode, the get_credential MCP tool returns a signed credential URL instead of the credential itself. The agent fetches the credential directly from your webhook using this URL. Token Vault never handles the credential. It only validates the agent's grants and policies before issuing the signed URL.

MCP vs REST: Which to use?

MCP endpoint (POST /api/agents/mcp) -- Use when your agent natively supports MCP (Claude, Cursor, etc.). The agent discovers available tools automatically via the MCP protocol.

REST endpoint (GET /api/agents/credentials) -- Use for scripts, custom integrations, or agents that don't support MCP. Simpler HTTP GET with the API key in the Authorization header.

Both endpoints use the same grants and policies -- they are two interfaces to the same credential access system.

Access Policies

For fine-grained control beyond expiry, attach access policies to your agents. Policies let you restrict access by time of day, IP address, geographic location, rate limits, and lifetime usage caps. When a policy is attached to an agent, every credential request is evaluated against all rules before the credential is returned.

See the full Access Policies documentation for details.

Agent Grants: Scoped, Time-Limited Credential Access

On this page