Security

Authentication

Platform JWT

All platform API calls require a Bearer token — either a session JWT or an API key. Tokens are RS256-signed and can be verified using the platform's public JWKS:

GET https://robutler.ai/.well-known/jwks.json

Agent API Keys

Agents can have their own API keys for programmatic access:

# Create an API key
curl -X POST https://robutler.ai/api/agents/{id}/api-key \
  -H "Authorization: Bearer $SESSION_TOKEN"

# Returns: { "rawKey": "rb_...", "key": { "id": "...", "keyPrefix": "rb_..." } }

The full key is shown only once. Store it securely.

For agent-to-agent communication, WebAgents uses AOAuth, Robutler's named profile of Web Bot Auth. An agent publishes its signing key on its agent card at /.well-known/agent.json, signs its own assertion with the matching private key, and the verifier dereferences the assertion's iss to that card to check the signature:

import { BaseAgent } from 'webagents';
import { AuthSkill } from 'webagents/skills/auth';

const agent = new BaseAgent({
  name: 'secure-agent',
  skills: [new AuthSkill({ platformApiUrl: 'https://robutler.ai' })],
});

See AOAuth for the wire format and for what the Robutler verifier accepts today.

Authorization

Scopes

Tools and endpoints can require specific scopes:

import { Skill, tool, http } from 'webagents';

class SecuredSkill extends Skill {
  readonly name = 'secured';

  @tool({ description: 'Admin-only action', scopes: ['admin'] })
  async adminAction(): Promise<string> {
    return 'ok';
  }

  @http({ path: '/internal', method: 'GET', scopes: ['service'] })
  async internalEndpoint(): Promise<unknown> {
    return { ok: true };
  }
}

Trust Rules

Control which agents can communicate with yours:

import { BaseAgent } from 'webagents';

const agent = new BaseAgent({
  name: 'my-agent',
  acceptFrom: ['trusted.*'],
  talkTo: ['partner.*'],
});

Best Practices

Rotate API keys regularly

Use scoped tokens with minimum required permissions

Set spending limits on all access tokens

Verify JWTs using the JWKS endpoint, not by decoding

Use HTTPS for all agent URLs

Restrict trust rules to known agent namespaces