Authentication

Overview

The MACP runtime requires authentication for most operations. The SDK supports two mechanisms:

Mechanism	Header	Use Case
Dev Agent	`x-macp-agent-id`	Local development (requires `MACP_ALLOW_DEV_SENDER_HEADER=1` on runtime)
Bearer Token	`Authorization: Bearer <token>`	Production deployments

Creating Auth Configs

Development

import { Auth } from 'macp-sdk-typescript';

// Simple dev agent — sets both agentId and senderHint
const auth = Auth.devAgent('alice');
// → Header: x-macp-agent-id: alice

Production

// Bearer token with optional sender hint
const auth = Auth.bearer('my-secret-token', 'alice');
// → Header: Authorization: Bearer my-secret-token

The senderHint is used by session helpers to populate the sender field on envelopes. The runtime may override this based on the authenticated identity.

Default vs Per-Operation Auth

Default Auth (Client-Level)

Set once, used for all operations:

const client = new MacpClient({
  address: '127.0.0.1:50051',
  auth: Auth.devAgent('coordinator'),
});

// All operations use coordinator's auth
await client.initialize();
const session = new DecisionSession(client);
await session.start({ intent: '...', participants: ['alice'], ttlMs: 60_000 });
await session.propose({ proposalId: 'p1', option: 'A' });

Per-Operation Auth (Multi-Agent)

Override auth for individual operations — essential when a single process acts on behalf of multiple agents:

// Coordinator starts the session
await session.start({ intent: '...', participants: ['alice', 'bob'], ttlMs: 60_000 });

// Alice evaluates (override auth)
await session.evaluate({
  proposalId: 'p1',
  recommendation: 'approve',
  confidence: 0.9,
  sender: 'alice',
  auth: Auth.devAgent('alice'),
});

// Bob votes (override auth)
await session.vote({
  proposalId: 'p1',
  vote: 'approve',
  sender: 'bob',
  auth: Auth.devAgent('bob'),
});

Session-Level Auth

Sessions can have their own default auth, independent of the client:

const session = new DecisionSession(client, {
  auth: Auth.bearer('session-specific-token', 'coordinator'),
});

Priority order: per-method auth > session auth > client auth.

Auth Validation

The SDK validates that exactly one of bearerToken or agentId is set:

import { validateAuth } from 'macp-sdk-typescript';

validateAuth({});                              // throws: either bearerToken or agentId required
validateAuth({ bearerToken: 'x', agentId: 'y' }); // throws: choose one, not both
validateAuth({ bearerToken: 'x' });            // ok
validateAuth({ agentId: 'y' });                // ok

Runtime Token Configuration

The Rust runtime supports token-based authorization with per-agent permissions:

{
  "tokens": [
    {
      "token": "coordinator-token",
      "sender": "coordinator",
      "allowed_modes": ["macp.mode.decision.v1", "macp.mode.quorum.v1"],
      "can_start_sessions": true,
      "max_open_sessions": 25,
      "can_manage_mode_registry": false
    },
    {
      "token": "worker-token",
      "sender": "worker",
      "can_start_sessions": false
    }
  ]
}

Configure via MACP_AUTH_TOKENS_FILE or MACP_AUTH_TOKENS_JSON environment variables on the runtime.

TLS

For production, enable TLS:

import * as fs from 'fs';

const client = new MacpClient({
  address: 'macp.example.com:50051',
  secure: true,
  rootCertificates: fs.readFileSync('/path/to/ca.pem'),
  auth: Auth.bearer('production-token', 'my-agent'),
});

The runtime must be configured with MACP_TLS_CERT_PATH and MACP_TLS_KEY_PATH.

On this page