Skip to main content

Credential JSON format

Switchboard's credential layer stores and retrieves JSON blobs via the credential helper protocol. The helpers are opaque — they don't enforce a schema — so the format is a Switchboard convention.

{
  "access_token": "gho_abc123...",
  "refresh_token": "ghr_def456...",
  "expires_at": "2026-06-15T00:00:00Z",
  "account_id": "acct_..."
}
  • access_token (required) — the credential value sent in the Authorization header.
  • refresh_token (optional) — OAuth refresh token, present for refresh-capable auth types.
  • expires_at (optional) — RFC 3339 timestamp of token expiry. null or absent = unknown.
  • account_id (optional) — provider account identifier, e.g. extracted from an OAuth JWT.

Resolution order​

When Switchboard needs a credential for a provider:

  1. If auth.type = "none" — no credential needed.
  2. It looks for agentkit-credential-<helper_name> in PATH (and next to its own binary), then runs <helper> get <identity>.
  3. If the helper isn't found or exits non-zero, it falls back to AGENTKIT_SWITCHBOARD_<NORMALIZED_IDENTITY> (uppercased, non-alphanumeric chars replaced with _).
  4. If neither produces a value, the provider is unconfigured and excluded from routing.