Get your first Delegation Token and make a brokered call to a third-party API. Starting with nothing installed? Get Started walks through the whole path, with a check at each step. Otherwise, choose your path:
Server
Run your own Cred server and let agents make brokered calls over HTTP. Handles token storage, encryption, consent flows, and OAuth provider management.
Requires: Node.js 22+, your own Cred server, at least one configured OAuth provider
Local
Fully standalone with @credninja/oauth + @credninja/vault. No account needed, no cloud dependency.
Requires: Node.js 22+, OAuth client credentials from your provider
npx @credninja/create-app my-cred-serveragent.env. Otherwise, create one once with await generateAgentIdentity() and save it securelyInstall the Cred SDK:
npm install @credninja/sdkOr for Python: pip install cred-auth
From your self-hosted Cred deployment, you need:
local for the default self-hosted flowAGENT_TOKEN configured on the server# Add to your .env file
CRED_BASE_URL=https://cred.example.com
CRED_APP_CLIENT_ID=local
CRED_AGENT_TOKEN=cred_at_...
CRED_AGENT_DID=did:key:...
CRED_AGENT_PRIVATE_KEY_HEX=...For local development only. Keep .env out of version control, and inject the token and key from a secret manager in production.
Initialize the client with your credentials:
import { Cred, ConsentRequiredError, importAgentIdentity } from '@credninja/sdk';
const cred = new Cred({
agentToken: process.env.CRED_AGENT_TOKEN!,
baseUrl: process.env.CRED_BASE_URL!,
});
// The agent's own key. It stays in this process.
const agent = importAgentIdentity({
did: process.env.CRED_AGENT_DID!,
privateKeyHex: process.env.CRED_AGENT_PRIVATE_KEY_HEX!,
});In a generated app, the operator runs:
npm run grant -- google calendar.readonlyAgainst any other server, use POST /admin/permissions. Without a Permission, the request in the next step gets permission_required once the user is connected.
Call delegateHandle() for a Delegation Token bound to the agent’s key, then use() to have Cred make the call:
async function getCalendarEvents(userId: string) {
try {
const credential = await cred.delegateHandle({
userId,
service: 'google',
appClientId: process.env.CRED_APP_CLIENT_ID!,
scopes: ['calendar.readonly'],
agentIdentity: agent,
});
// Cred makes the call. The provider token stays on the server.
return await cred.use({
token: credential.token,
url: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
method: 'GET',
agentIdentity: agent,
});
} catch (error) {
if (error instanceof ConsentRequiredError) {
// This user hasn't connected the service yet. See the next step.
console.log('Connect this user at:', error.consentUrl);
return null;
}
throw error;
}
}The first request for a user fails with ConsentRequiredError. Its consentUrl is a single-use link that expires after 10 minutes.
/admin/login as the operator. The link does not work without that session.consentUrl and complete the provider’s sign-in as the person connecting the account.getCalendarEvents() again.To connect a user before any request, open /connect?user_id=<id> as the operator.
No remote server needed. Use standalone packages for fully local credential management:
npm install @credninja/oauth @credninja/vaultimport { OAuthClient, GoogleAdapter } from '@credninja/oauth';
import { createVault } from '@credninja/vault';
// 1. Run OAuth flow
const google = new OAuthClient({
adapter: new GoogleAdapter(),
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
redirectUri: 'http://localhost:3000/callback',
});
const { url, codeVerifier } = await google.getAuthorizationUrl({
scopes: ['calendar.readonly'],
});
// 2. Store tokens in encrypted local vault
const vault = await createVault({
passphrase: process.env.VAULT_PASSPHRASE!,
storage: 'sqlite',
path: './cred-vault.db',
});
await vault.store({
provider: 'google',
userId: 'user-123',
accessToken: tokens.access_token,
refreshToken: tokens.refresh_token,
expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
scopes: ['calendar.readonly'],
});
// 3. Retrieve (auto-decrypts, auto-refreshes if adapter provided)
const creds = await vault.get({ provider: 'google', userId: 'user-123' });See @credninja/oauth and @credninja/vault for full standalone documentation. When you want a separate broker process instead of local-only storage, deploy @credninja/server.
When you called delegateHandle() and use():
Install the Cred MCP server for interactive credential delegation:
{
"mcpServers": {
"cred": {
"command": "npx",
"args": ["-y", "@credninja/mcp"],
"env": {
"CRED_BASE_URL": "https://cred.example.com",
"CRED_AGENT_TOKEN": "<from your secret store>",
"CRED_APP_CLIENT_ID": "local",
"CRED_AGENT_DID": "did:key:...",
"CRED_AGENT_PRIVATE_KEY_HEX": "<from your secret store>"
}
}
}
}Tools include cred_delegate and cred_use. See the MCP README for the full list.