Codios Quickstart: Add cryptographic authorization to AI agents in 5 minutes

API keys authenticate. They don't authorize.

For AI agents calling each other, that's a problem. Agents need scope, limits, expiry, and audit trails — not just a shared string.

Codios solves this with signed capability contracts. Here's how to set it up in 5 minutes.

What you'll need

• A Codios account (free at codios.midlantics.com)
• Node.js installed
• 5 minutes

Step 1: Get your API key

1. Log into the Codios dashboard
2. Go to the API Keys tab
3. Click Create key, name it (e.g., "local-dev")
4. Copy the key starting with codios_sk_ — it's shown once

Store it in .env:

CODIOS_API_KEY=codios_sk_...

Step 2: Install the CLI (easiest path)

npm install -g @codios/cli

Configure it with your API key:

echo "api_key=$CODIOS_API_KEY" > .codios

Or set environment variables:

Step 3: Generate keypairs for your agents

Every agent gets an Ed25519 keypair. The public key becomes a verifiable DID.

codios keygen --save .env

Output:

 DID            did:key:z6MkfbSn...                    
 Public key     FwxlZ5Z4IInzCGbW...                     
 Private key    myYQIoGDC+W94GN9...                      

Run this twice — once for the caller agent, once for the service agent.

Step 4: Register your agents

# Register the caller (billing agent)
codios register --name billing-agent --public-key <caller-public-key>

# Register the service (payment agent)
codios register --name payment-service --public-key <service-public-key>

Alternative via dashboard:

• Go to Agents tab → Register agent
• Leave public key blank — Codios generates one for you
• Copy the private key (shown once)

Step 5: Issue a contract

A contract grants the caller permission to call specific actions on the service agent.

codios issue \
    --issuer did:key:z6MkfbSn... \
    --subject did:key:z6Mkg1EP... \
    --actions transfer,quote \
    --max-calls 1000 \
    --ttl 3600

Output:

X-Codios-Contract: eyJpc3N1ZXJfZGlkIjoiZGl...

That base64 string is your contract token. Via dashboard:

• Contracts tab → Connect agents
• 4-step wizard: Issuer → Targets → Permissions → Review
• Each target gets its own independent contract

Contract status: active → expired (TTL elapsed) or revoked (manual)

Step 6: Protect your service with middleware

Install the SDK:

npm install @codios/sdk

Add the guard to your Express app:

typescript import express from "express" import { codiosGuard } from "@codios/sdk"

const app = express()

app.post( "/transfer", codiosGuard({ action: "transfer", publicKey: process.env.SERVICE_PUBLIC_KEY, gatewayUrl: "https://codios-api.midlantics.com", }), (req, res) => { res.json({ ok: true }) } )

app.listen(3000)

**For Python/FastAPI:**

```python
from codios.middleware import CodiosMiddleware

app.add_middleware(CodiosMiddleware, action="transfer")

Step 7: Call the protected service

The caller attaches the contract token as a header:

const response = await fetch("http://localhost:3000/transfer", {
  method: "POST",
  headers: {
    "Content-Type":      "application/json",
    "X-Codios-Contract": contractToken,
  },
  body: JSON.stringify({ amount: 100 }),
})

What happens on every request

If any check fails → HTTP 403 or 409. The request never reaches your handler.

Dashboard at a glance

Once agents are running, the dashboard gives you:

Try the demo first

No account needed: codios.midlantics.com/demo

The interactive sandbox lets you:

1. Create two agents (Ed25519 keypairs)
2. Issue a contract in the wizard
3. Test enforcement in real time

See the offline verification in action before installing anything.

Next steps

• Add heartbeat – Call POST /agents/{id}/heartbeat every minute to keep status green
• Set up alert rules – Get email notifications when something goes wrong
• Review audit log – See every decision
• Use the API directly – codios.midlantics.com/docs/api

Why Codios?

API keys were designed for humans. AI agents are different — autonomous, fast, and chained.

Codios gives you the security model agents actually need: identity, scope, limits, expiry, and full audit trails — all with 1–2ms overhead.

Get started: codios.midlantics.com

Documentation: codios.midlantics.com/docs