Authentication

Creddy supports two authentication methods. Choose based on your needs:

Both methods work on all API endpoints.

OIDC Authentication (Recommended)

Standard OAuth 2.0 client credentials flow. Agents get short-lived JWTs.

Setup

1. Start server with OIDC enabled:

creddy server --oidc-issuer https://creddy.example.com

2. Create agent (save the OIDC credentials):

creddy agent create my-agent --can github
# Returns client_id and client_secret

Agent Authentication

# Step 1: Exchange credentials for access token
ACCESS_TOKEN=$(curl -s -X POST https://creddy.example.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=agent_f8e7d6" \
  -d "client_secret=cks_xyz789" \
  | jq -r .access_token)
 
# Step 2: Use access token for API calls
curl https://creddy.example.com/v1/credentials/github \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Token Details

Access tokens are JWTs containing:

• agent_id — Unique agent identifier
• agent_name — Human-readable name
• scopes — Granted permissions
• exp — Expiration (1 hour default)

See OIDC Provider for full details.

Vend Token Authentication

Simple bearer token. Creddy “vends” credentials directly — no OAuth exchange needed.

Setup

1. Create agent:

creddy agent create my-agent --can github
# Returns token: ckr_abc123...

Agent Authentication

# Use token directly
curl https://creddy.example.com/v1/credentials/github \
  -H "Authorization: Bearer ckr_abc123..."

Token Details

• Format: ckr_ + 48 hex characters
• Lifetime: Permanent (until agent deleted)
• Stored: SHA256 hash on server

Enrollment Flow

For interactive enrollment (human approval required):

Agent Side

creddy enroll https://creddy.example.com --name my-agent --can github

This generates a keypair locally and sends the public key to the server.

Admin Side

# List pending
creddy admin pending
 
# Approve
creddy admin approve enr_abc123

After approval, the agent receives credentials automatically.

Auto-Approval

For CI/CD, configure auto-approve rules:

# creddy.yaml
policies:
  - name: ci-runners
    pattern: "ci-*"
    scopes:
      - "github:*"
    auto_approve: true
    max_agent_lifetime: 24h

Agents matching the pattern are approved immediately with the specified scopes.

Choosing a Method

Use OIDC when:

• Running in production
• Need AWS/GCP federation (AssumeRoleWithWebIdentity)
• Want short-lived tokens
• Need audit trails with identity claims

Use Vend tokens when:

• Quick local testing
• Simple shell scripts
• Don’t need federation
• Single static credential is fine

Security Considerations

Credential Storage

OIDC:

• Store client_id and client_secret in secrets manager
• Access tokens are short-lived (1 hour)
• Rotate client_secret periodically

Vend:

• Store ckr_ token in secrets manager
• Token is permanent — rotate by creating new agent
• Delete old agents after rotation

Network Security

• Always use HTTPS in production
• Bind server to Tailscale/private network
• Use --listen to restrict access

Revocation

OIDC:

• Rotate signing keys: creddy admin keys rotate
• All tokens become invalid
• Agents must re-authenticate

Vend:

• Delete agent: creddy agent delete my-agent
• Token immediately invalid

API Reference

Get Token (OIDC)

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=agent_xxx
&client_secret=cks_xxx
&scope=openid github

Authenticated Requests

GET /v1/credentials/github
Authorization: Bearer <token>

Works with both OIDC access tokens (eyJ...) and legacy tokens (ckr_...).

Check Identity

GET /v1/status
Authorization: Bearer <token>

Returns agent info and active credentials.