Getting Started

Creddy is an OIDC provider for AI agents. Agents authenticate via OAuth 2.0 and get short-lived, scoped credentials. Your master secrets never leave the server.

Architecture:


┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│    Agent     │ ──────▶ │    Creddy    │ ──────▶ │   GitHub     │
│  (your bot)  │  OIDC   │   Server     │  master │   AWS, etc   │
│              │ ◀────── │   (IdP)      │  creds  │              │
│              │  JWT    │              │         │              │
│              │         │              │         │              │
└──────────────┘         └──────────────┘         └──────────────┘

Get it running in 5 minutes.

1. Install Creddy

On your server (where master credentials will live):


curl -fsSL https://get.creddy.dev/install.sh | sudo sh

2. Start the Server

Start Creddy with your OIDC issuer URL:


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

Output:


Database: /root/.creddy/creddy.db
OIDC Issuer: https://creddy.example.com
Listening on 127.0.0.1:8400

The --oidc-issuer flag is required. This URL must be reachable by services that will verify agent tokens.

Production: See Server Setup for TLS, systemd, and Tailscale configuration.

3. Add a Backend

Install the GitHub plugin:


creddy plugin install github
 
creddy backend add github \
  --app-id YOUR_APP_ID \
  --private-key /path/to/private-key.pem \
  --installation-id YOUR_INSTALLATION_ID

Need a GitHub App? See GitHub Integration.

4. Create an Agent


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

Output:


{
  "id": "a1b2c3d4",
  "name": "my-agent",
  "oidc": {
    "client_id": "agent_f8e7d6",
    "client_secret": "cks_xyz789..."
  },
  "scopes": ["github:owner/repo"]
}

Save these credentials! They’re only shown once.

5. Use Credentials (Agent Side)

Agents authenticate using standard OAuth 2.0 client credentials:


# Set these in your agent's environment
export CREDDY_URL="https://creddy.example.com"
export CREDDY_CLIENT_ID="agent_f8e7d6"
export CREDDY_CLIENT_SECRET="cks_xyz789..."
 
# 1. Get access token (OAuth 2.0 client credentials)
ACCESS_TOKEN=$(curl -s -X POST $CREDDY_URL/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$CREDDY_CLIENT_ID" \
  -d "client_secret=$CREDDY_CLIENT_SECRET" \
  | jq -r .access_token)
 
# 2. Get GitHub credential
GITHUB_TOKEN=$(curl -s "$CREDDY_URL/v1/credentials/github?ttl=10m" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -r .token)
 
# 3. Use it
gh api repos/owner/repo --header "Authorization: token $GITHUB_TOKEN"

Or use any OIDC client library:


import { Issuer } from 'openid-client';
 
const issuer = await Issuer.discover(process.env.CREDDY_URL);
const client = new issuer.Client({
  client_id: process.env.CREDDY_CLIENT_ID,
  client_secret: process.env.CREDDY_CLIENT_SECRET,
});
 
const { access_token } = await client.grant({
  grant_type: 'client_credentials',
});

What Just Happened?

Server holds your GitHub App credentials (the master secret)
Agent authenticated to Creddy via OIDC, got a signed JWT
Creddy issued a 10-minute GitHub token scoped to owner/repo
Agent used the temporary token — it auto-expires, no cleanup needed

The agent never saw your GitHub App private key.

Next Steps

OIDC Provider — Deep dive into OIDC flows and federation
Server Setup — Production configuration
Concepts — Agents, scopes, TTLs explained
Integrations — GitHub, Anthropic, OpenAI, and more