Agent Grants: Scoped, Time-Limited Credential Access

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

Creating an Agent

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

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

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

Granting Credentials

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

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

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.

Direct-From-Webhook Credential Retrieval

Token Vault never sees your plaintext credentials during agent access. When an agent requests a credential:

1. The agent sends GET /api/agents/credentials?service=github to Token Vault.
2. Token Vault validates the agent's API key, checks the grant, and evaluates ABAC policies.
3. Token Vault generates a signed credential ticket (HMAC-SHA256) and returns a 307 redirect to your webhook's /v1/credential endpoint.
4. The agent's HTTP client follows the redirect and receives the credential directly from your webhook.
5. Your webhook verifies the ticket signature, reads the credential from its own storage, 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.

Revocation

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.

Connecting via MCP

Two interchangeable ways to authenticate — both resolve to the same (user, agent) identity with the same grants and policies:

OAuth 2.1 (recommended for MCP clients). Point the client at the endpoint with no credentials; it discovers Token Vault's authorization server and walks you through consent in the browser:

claude mcp add --transport http token-vault https://api.tokenvault.uk/api/agents/mcp

No key handling at all — see OAuth 2.1 for MCP Clients.

Static tvagent_ key. For server-side agents you configure by hand:

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

Either way, enable MCP access for the agent first (toggle "MCP Enabled" on the agent detail page — or approve it inline during the OAuth consent step).

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: 2026-08-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"
    }]
  }
}

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.