Get Started
Run a Cred server on your machine, connect a GitHub account, grant an agent read access, make a brokered call, find it in the audit log, and revoke the agent. Each step ends with a check you can run.
You need
- Node.js 22 or later
- A GitHub account and an OAuth app with the callback URL
http://localhost:3456/connect/github/callback
Create the server
npx @credninja/create-app my-cred-server
cd my-cred-server.env configures the server. agent.env holds what your agent needs, including a new agent identity. Both are in .gitignore, and neither should be shared.
.env, agent.env and grant-agent.mjs, and grep SINGLE_USER_MODE .env includes SINGLE_USER_MODE=false.Add GitHub and start
Add your OAuth app’s values to .env, then start the server:
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secretnpm startcurl -s http://localhost:3456/health answers with "status":"ok" and "providers":["github"].Connect an account
- 1. Open
http://localhost:3456/admin/loginand sign in withADMIN_TOKENfrom.env. - 2. Open
http://localhost:3456/connect?user_id=alice. - 3. Under GitHub, tick Repos (all), which is the
reposcope. Choose Connect, and approve it at GitHub.
source ./.env
curl -s -H "Authorization: Bearer $AGENT_TOKEN" \
"http://localhost:3456/api/v1/connections?user_id=alice"repo is GitHub’s own scope, and GitHub has no read-only one. In step 5 you grant the agent github.read, a narrower scope that Cred enforces. The stored token still has repo and stays on the server.
"slug":"github" and "scopesGranted":["repo"].Run an agent with no Permission
npm install @credninja/sdkSave this as agent.mjs:
import { Cred, ConsentRequiredError, CredError, importAgentIdentity } from '@credninja/sdk';
const cred = new Cred({
agentToken: process.env.CRED_AGENT_TOKEN,
baseUrl: process.env.CRED_BASE_URL,
});
const agent = importAgentIdentity({
did: process.env.CRED_AGENT_DID,
privateKeyHex: process.env.CRED_AGENT_PRIVATE_KEY_HEX,
});
const repo = 'https://api.github.com/repos/octocat/hello-world';
try {
const credential = await cred.delegateHandle({
userId: 'alice',
service: 'github',
appClientId: 'local',
scopes: ['github.read'],
agentIdentity: agent,
});
console.log('Scopes:', credential.scopes.join(', '));
const read = await cred.use({
token: credential.token,
agentIdentity: agent,
url: repo,
method: 'GET',
});
console.log('Read:', read.status);
// github.read doesn't cover this, so Cred refuses it without calling GitHub.
await cred.use({
token: credential.token,
agentIdentity: agent,
url: `${repo}/issues`,
method: 'POST',
body: { title: 'From my agent' },
}).catch((error) => console.log('Write refused:', error.code));
} catch (error) {
if (error instanceof ConsentRequiredError) console.log('Connect alice first.');
else if (error instanceof CredError) console.log('Refused:', error.statusCode, error.code);
else throw error;
}node --env-file=agent.env agent.mjsRefused: 403 permission_required. The account is connected and the agent holds the right token and key, and it still receives nothing.Grant the Permission
npm run grant -- github github.readRead what it printed. A Permission is per agent and service, not per user, so this agent can act for every user connected to this server. See Current Limits.
Granted did:key:... on github, for every user of this server: github.read.Make a brokered call
node --env-file=agent.env agent.mjsScopes: github.read, Read: 200 and Write refused: scope_insufficient. The agent never held the GitHub token, and the write never reached GitHub.Read the audit entry
source ./.env
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:3456/admin/audit?service=github&limit=5"
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:3456/admin/audit/verify"The successful call looks like this, shortened:
{
"action": "access",
"service": "github",
"userId": "alice",
"actor": {
"type": "agent",
"id": "did:key:z6Mk...",
"fingerprint": "OXetrbOs..."
},
"metadata": {
"outcome": "success",
"scopesGranted": ["github.read"],
"webBotAuth": {
"delegationId": "del_1402...",
"origin": "https://api.github.com",
"route": "/repos/{id}/{id}",
"brokered": true,
"method": "GET",
"status": 200
}
}
}The route has its identifiers removed, so it holds no repository name or query string. /admin/audit/verify recomputes the hash chain and returns its head. Record the head outside the host to detect removal of the newest entries.
access event has actor.id equal to CRED_AGENT_DID in agent.env, and a deny event from the same agent has errorMessage set to scope_insufficient. /admin/audit/verify answers "ok":true.Revoke the agent
Find the Permission’s id, then delete it:
source ./.env
source ./agent.env
curl -s -G -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:3456/admin/permissions" \
--data-urlencode "agent_id=$CRED_AGENT_DID" \
--data-urlencode "connection_id=github"curl -s -o /dev/null -w '%{http_code}\n' -X DELETE \
-H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:3456/admin/permissions/<permission id>"
node --env-file=agent.env agent.mjsThe agent stays out for every user of the service until you grant it again. To restore it, run npm run grant -- github github.read.
DELETE answers 204, and the script prints Refused: 403 agent_access_revoked. A token the agent still held would get 401 delegation_revoked.Next Steps
Quickstart
Add the SDK to an agent you already have, including Python and MCP.
Operation Enforcement
What each provider’s tables map, and the read scopes on Cred’s side.
Error Codes
The refusals an agent can meet, and what each one means.
Current Limits
What to know before you run this for more than one user.