Agent Credentials API

GET /api/agents/credentials

Retrieve a credential the calling agent has been granted. On success Token Vault validates the grant and ABAC policies, then answers with a 307 redirect to your webhook's /v1/credential; the agent's HTTP client follows it and receives the credential directly from the webhook. Use a client that follows redirects (curl -L; Python requests follows by default).

Authentication

The agent's tvagent_… key, one of three ways (checked in this order):

A tvsess_… OAuth session token works identically on the MCP endpoint — see OAuth 2.1 for MCP Clients.

Parameters

Response — single credential (service set)

Token Vault answers 307 Temporary Redirect with a Location pointing at your webhook, which returns:

{
  "token": {
    "accessToken": "ghp_…",
    "refreshToken": "ghr_…",
    "serviceName": "github",
    "tokenType": "pat",
    "createdAt": "2026-02-01T10:00:00Z"
  }
}

Exact fields depend on token type — a TOTP token returns a current one-time code as accessToken, a raw GCP credential returns a short-lived minted token. See the brokering guides.

Response — list mode (service omitted)

Token Vault answers directly (no redirect, no credential material):

{
  "grants": [
    {
      "serviceName": "github",
      "grantExpiresAt": null,
      "refreshPolicy": "none",
      "sourceGroupId": null
    },
    {
      "serviceName": "google",
      "grantExpiresAt": "2026-08-01T12:00:00Z",
      "refreshPolicy": "auto",
      "sourceGroupId": "grp_ab12"
    }
  ]
}

Expired grants are filtered out. sourceGroupId is set when the grant came from a token group.

Errors

{
  "error": "Access denied by policy",
  "policy": "office-hours",
  "rule": "time_window",
  "reason": "Outside allowed window 09:00-18:00 Europe/London",
  "code": "POLICY_DENIED"
}

If your webhook is offline, the agent's redirect fetch fails at the webhook — that is the kill switch doing its job.