Overview

Cred is credential delegation middleware for AI agents. When your agent needs to access a user’s Google Calendar, Slack workspace, or GitHub repos, Cred validates the agent’s identity, checks that the user consented, and returns a short-lived access token. Refresh tokens never leave the vault.

There are three actors in the Cred ecosystem:

Quick Start

1. 1. Install the SDK

   npm install @credninja/sdk

2. 2. Create a CredClient

   import { CredClient } from '@credninja/sdk';
   
   const cred = new CredClient({
     agentToken: process.env.CRED_AGENT_TOKEN,
     appClientId: process.env.CRED_APP_CLIENT_ID,
     baseUrl: 'https://api.cred.ninja',
   });

3. 3. Request delegated credentials

   try {
     const { accessToken } = await cred.delegate({
       userId: 'user-123',
       service: 'google',
       scopes: ['calendar.readonly'],
     });
   
     // Use the access token with Google API
     const response = await fetch(
       'https://www.googleapis.com/calendar/v3/calendars/primary/events',
       { headers: { Authorization: `Bearer ${accessToken}` } }
     );
   } catch (error) {
     if (error instanceof ConsentRequiredError) {
       // Redirect user to consent URL
       return redirect(error.consentUrl);
     }
     throw error;
   }

See the full quickstart guide for a complete walkthrough.

OAuth 2.0 Flow

Cred implements the Authorization Code flow with PKCE (RFC 7636) for user consent. When a user authorizes an OAuth connection, Cred stores the refresh token encrypted in the vault.

Credential Delegation

Cred’s delegation pipeline validates agent identity, checks user consent, and returns short-lived access tokens. Agents call third-party APIs directly with the delegated token.

7-Step Pipeline

1. 1. Validate agent token - Verify cred_at_* token is valid and active
2. 2. Lookup app - Find the application associated with the agent
3. 3. Check consent - Verify user has authorized this app for the requested service
4. 4. Validate scopes - Ensure requested scopes are subset of granted scopes
5. 5. Check cached token - Return cached access token if still valid
6. 6. Refresh if expired - Use refresh token to get new access token
7. 7. Return token - Return short-lived access token to agent

POST https://api.cred.ninja/api/delegate
Authorization: Bearer cred_at_...
Content-Type: application/json

{
  "user_id": "user-123",
  "service": "google",
  "scopes": ["calendar.readonly"]
}

Supported Services

Credential Vault

Users authorize OAuth connections through Cred. Refresh tokens are encrypted with AES-256-GCM and stored in the vault. They are decrypted only in-memory during token refresh and never exposed to agents or developers.

Agent Authentication

Agents authenticate using agent tokens (cred_at_*). Developers create agents in their app settings and generate tokens.

# Generate agent token
POST /api/agents/token
Content-Type: application/json

{
  "client_id": "your_app_client_id",
  "client_secret": "your_app_client_secret"
}

# Response
{
  "access_token": "cred_at_...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Agent tokens are SHA-256 hashed before storage. The plaintext token is returned only once at creation time.

API Reference

SDK

The official TypeScript SDK handles delegation requests, consent flow handling, and DID agent identity.

npm install @credninja/sdk

import { CredClient, ConsentRequiredError } from '@credninja/sdk';

const cred = new CredClient({
  agentToken: process.env.CRED_AGENT_TOKEN,
  appClientId: process.env.CRED_APP_CLIENT_ID,
});

// Request delegated credentials
try {
  const { accessToken, expiresAt } = await cred.delegate({
    userId: 'user-123',
    service: 'slack',
    scopes: ['channels:read', 'chat:write'],
  });

  // Use accessToken with Slack API directly
} catch (error) {
  if (error instanceof ConsentRequiredError) {
    // User hasn't authorized this app yet
    // Redirect to error.consentUrl
  }
}

Python SDK

pip install cred-auth

from cred import CredClient, ConsentRequiredError

cred = CredClient(
    agent_token=os.environ["CRED_AGENT_TOKEN"],
    app_client_id=os.environ["CRED_APP_CLIENT_ID"],
)

try:
    result = cred.delegate(
        user_id="user-123",
        service="github",
        scopes=["repo", "read:user"],
    )
    # Use result.access_token with GitHub API
except ConsentRequiredError as e:
    # Redirect user to e.consent_url

Audit & Compliance

Cred maintains an append-only audit log for all delegation requests, token issuances, and consent changes. Credential values are redacted from logs.

Verify Receipt

import { verifyDelegationReceipt } from '@credninja/sdk';

const isValid = verifyDelegationReceipt(receipt);