Concepts

Core concepts in Creddy.

Identity vs Credentials

Creddy provides two distinct things:

Layer	What	Example
Identity	Proof of who the agent is	JWT with `agent_id`, `scopes`
Credentials	Access to external services	GitHub token, AWS creds

Identity (via OIDC) proves the agent is who they claim to be. Credentials grant access to specific backends.


Agent authenticates    Agent requests credential    Agent uses credential
      │                        │                           │
      ▼                        ▼                           ▼
┌──────────┐            ┌──────────┐                ┌──────────┐
│  OIDC    │            │  Vend    │                │  GitHub  │
│  Token   │ ─────────▶ │  GitHub  │ ─────────────▶ │   API    │
│  (JWT)   │            │  Token   │                │          │
└──────────┘            └──────────┘                └──────────┘
   "I am                 "Give me                    "Here's
   agent-123"            GitHub access"              the code"

Agents

An agent is an identity that can request credentials. Typically an AI assistant, CI runner, or automated script.


creddy agent create my-bot --can "github:owner/repo"

Each agent has:

Name — Human-readable identifier
Scopes — What backends/resources it can access
Credentials — How it authenticates (OIDC or vend token)

Agent Credentials

When created, agents receive two sets of credentials:

Type	Format	Use
Vend Token	`ckr_abc123...`	Direct API access
OIDC	`client_id` + `client_secret`	OAuth flow, federation

Both work for all API endpoints. See Authentication for details.

Agent Lifecycle

Agents can be:

Permanent — No expiration, deleted manually
Time-limited — Auto-deleted after TTL expires

Create a time-limited agent via API:


curl -X POST https://creddy.example.com/v1/admin/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task-runner",
    "scopes": ["github:owner/repo"],
    "expires_in": "4h"
  }'

The agent is automatically reaped when TTL expires.

Self-Deletion

Agents can delete themselves when their work is complete:


curl -X DELETE https://creddy.example.com/v1/self \
  -H "Authorization: Bearer $AGENT_TOKEN"

This:

Revokes all active backend credentials
Deletes signing keys
Removes the agent

Use TTL as a safety net, self-delete for clean shutdown.

Backends

A backend is an external service Creddy can issue credentials for.


# Install plugin
creddy plugin install github
 
# Configure backend
creddy backend add github \
  --app-id 123456 \
  --private-key ./key.pem

Creddy holds the master credentials. Agents get short-lived tokens.

Backend Modes

Backends work in one of two modes:

Mode	How it works	Backends
Vend	Creddy creates real credential at backend. Agent uses it directly.	GitHub, AWS, Doppler, OpenAI, Tailscale
Proxy	Backend doesn’t support ephemeral keys. Requests go through Creddy.	Anthropic

Vend mode (most backends):


TOKEN=$(creddy get github)
gh api repos/owner/repo  # Direct to GitHub

Proxy mode (Anthropic):


TOKEN=$(creddy get anthropic)
curl http://creddy:8400/v1/proxy/anthropic/v1/messages  # Through Creddy

Available Backends

Backend	Mode	Credential Type
`github`	Vend	Installation tokens via GitHub App
`aws`	Vend	STS temporary credentials
`doppler`	Vend	Service tokens
`openai`	Vend	Service account API keys
`tailscale`	Vend	Auth keys
`anthropic`	Proxy	Proxy tokens (via Creddy)

See Integrations for setup guides.

Scopes

Scopes define what an agent can access. Format: backend:resource:permission

Examples


# Specific repo, read-only
github:owner/repo:read
 
# All repos in org, read-write
github:myorg/*:write
 
# Any GitHub access
github:*
 
# Multiple backends
github:owner/repo doppler:project/config

Wildcards

github:* — All GitHub permissions
github:owner/* — All repos in owner
* — Everything (use carefully)

Scope Validation

When an agent requests credentials, Creddy checks:

Is the backend in the agent’s scopes?
Is the specific resource allowed?
Is the permission level allowed?


# Agent has: github:owner/repo:read
# Requests: github:owner/repo  ✅ allowed
# Requests: github:other/repo  ❌ denied

Credentials (Ephemeral Tokens)

When an agent requests a credential, Creddy issues a short-lived token:


curl https://creddy.example.com/v1/credentials/github?ttl=10m \
  -H "Authorization: Bearer $TOKEN"

Response:


{
  "token": "ghs_xxxxxxxxxxxx",
  "expires_at": "2026-03-06T13:10:00Z",
  "ttl": "10m0s"
}

TTL (Time to Live)

How long the credential is valid:

Use Case	Recommended TTL
Quick API call	5–15 minutes
CI job	1 hour
Long task	2–4 hours

Default: 10 minutes. Maximum depends on backend.

Revocation

Some backends support early revocation:


# List active credentials
creddy list
 
# Revoke one
creddy revoke <credential-id>

Otherwise, credentials expire automatically.

OIDC

Creddy is an OpenID Connect provider. Agents can authenticate using standard OAuth 2.0.

Endpoints

Endpoint	Purpose
`/.well-known/openid-configuration`	Discovery metadata
`/.well-known/jwks.json`	Public keys
`/oauth/token`	Get access token
`/oauth/userinfo`	Get agent info

Token Types

Access Token — JWT for API authentication


{
  "sub": "agent-uuid",
  "agent_name": "my-bot",
  "scopes": ["github:owner/repo"],
  "exp": 1709740800
}

ID Token — JWT for identity verification (federation)

See OIDC Provider for full details.

Admin Scopes

Agents can be granted admin permissions to manage other agents and resources.

Available Scopes

Scope	Permission
`admin:agents:read`	List agents
`admin:agents:write`	Create/delete agents
`admin:backends:read`	List backends
`admin:backends:write`	Create/delete backends
`admin:tokens:read`	List active tokens
`admin:tokens:write`	Revoke tokens
`admin:audit:read`	View audit log
`admin:enrollments:read`	List pending enrollments
`admin:enrollments:write`	Approve/reject enrollments
`admin:plugins:write`	Reload plugins
`admin:keys:read`	View signing keys

Wildcards

admin:* — Full admin access
admin:agents:* — Read and write agents

Provisioner Pattern

Create a “provisioner” agent that manages other agents:


# One-time setup (on server)
creddy agent create provisioner --can "admin:agents:*"
 
# Provisioner creates task agents remotely
curl -X POST https://creddy.example.com/v1/admin/agents \
  -H "Authorization: Bearer $PROVISIONER_TOKEN" \
  -d '{
    "name": "task-123",
    "scopes": ["github:owner/repo"],
    "expires_in": "4h"
  }'

The provisioner is a trusted process that:

Authenticates to Creddy with admin credentials
Creates agents for specific tasks
Passes credentials to agent processes
Agents self-delete when done (or TTL expires)

Audit Log

Every credential operation is logged:


creddy audit list --since 24h


{
  "timestamp": "2026-03-06T12:30:00Z",
  "action": "token_issued",
  "agent": "my-bot",
  "backend": "github",
  "ttl": "10m",
  "ip": "100.64.0.1"
}

Logged Events

agent_created — New agent enrolled
token_issued — Credential generated
token_revoked — Credential revoked early
scopes_amended — Agent scopes changed

Signing Keys

Creddy uses cryptographic keys for:

OIDC Tokens — RS256 JWTs
Git Commits — GPG keys per agent

OIDC Keys


# View keys
curl https://creddy.example.com/.well-known/jwks.json
 
# Rotate (admin)
creddy admin keys rotate

Old keys remain valid during grace period.

Git Signing Keys

Each agent gets a GPG key for signed commits:


# Agent retrieves their key
creddy signing-key --format git

Returns key + git config for commit.gpgsign.

Summary


┌─────────────────────────────────────────────────────────────┐
│                      CREDDY SERVER                          │
│                                                             │
│  Backends         Agents           OIDC                     │
│  ┌─────────┐      ┌─────────┐      ┌─────────┐             │
│  │ github  │      │ my-bot  │      │ keys    │             │
│  │ aws     │      │ ci-job  │      │ tokens  │             │
│  │ doppler │      │ deploy  │      │ jwks    │             │
│  └─────────┘      └─────────┘      └─────────┘             │
│       │                │                │                   │
│       └────────────────┼────────────────┘                   │
│                        │                                    │
│              ┌─────────┴─────────┐                         │
│              │   Audit Log       │                         │
│              │   (all actions)   │                         │
│              └───────────────────┘                         │
└─────────────────────────────────────────────────────────────┘