Skip to main content

What federation does

When two services both run theAuth, an agent created at Service A can authenticate at Service B without creating a new account. The agent’s identity, trust score, permissions, and delegation scope travel with it in a short-lived, signed JWT called a federation token. This is useful when:
  • A user has agents in multiple SaaS apps that need to talk to each other
  • An agent orchestrator delegates sub-tasks to agents registered at different services
  • You run a multi-service architecture and want unified agent identity
Federation tokens are not long-lived sessions. They are short-lived credentials (5 minutes by default) that prove “this agent exists at Service A, with these permissions.” The module does not track used tokens, so a token can be presented more than once until it expires. Use audience restriction and short TTLs to limit replay.

How it works

The module only signs and verifies tokens, and it does not look agents up in your database. The agentId, permissions and trust score you pass to issueFederationToken are exactly what the token carries.
  1. Service A issues a federation token for one of its agents
  2. The agent presents that token to Service B
  3. Service B fetches Service A’s public key from /.well-known/theauth-federation.json
  4. Service B verifies the token signature, checks expiry, and applies trust level rules
  5. Service B now has a FederatedAgent object with the agent’s identity and (possibly downgraded) permissions
The source instance signs tokens with an EdDSA keypair. The target instance only needs the public key to verify.

Setup

Trust levels

When you add a trusted instance, you choose how much to trust its claims. With limited trust, any permission containing “write” or “admin” is removed from the federated agent’s permissions. The trust score is capped at 0.5 regardless of what the source instance claims. With verify-only trust, you only confirm the agent exists at the source instance. No permissions or trust are transferred. Useful when you want to check identity before assigning local permissions.

Issuing federation tokens

Service A issues a token for one of its agents:
The token is a JWT containing:
  • sub: agent ID
  • iss: source instance ID
  • aud: target instance ID (if specified)
  • exp: expiration time
  • permissions: agent permissions array
  • trust_score: source instance’s trust assessment (0-1)
  • delegation_scope: what the agent is allowed to delegate
  • credential: optional embedded Verifiable Credential JWT

Verifying federation tokens

Service B verifies the token:
Verification checks:
  1. Token signature matches the source instance’s public key
  2. Token has not expired
  3. Source instance is in the trusted list and has a public key configured
  4. Audience matches this instance (if audience is set in the token)
  5. Trust level rules are applied to downgrade permissions if needed

Embedding verifiable credentials

You can attach a W3C Verifiable Credential to the federation token for offline verification. This is useful when the target instance needs cryptographic proof of the agent’s capabilities that does not depend on the source instance’s availability.
On the receiving side, result.data.credential will contain the VC JWT, which you can verify independently using createVCVerifier.

Discovery protocol

Each theAuth instance can publish its identity at:
Response:
Use discoverInstance to fetch and parse this:
Discovered instances default to verify-only trust. You must explicitly upgrade the trust level after discovery.

Security considerations

Federation tokens carry permissions across trust boundaries. Think carefully about trust levels.
  • Short TTLs: Default is 5 minutes. Keep tokens short-lived to limit blast radius.
  • Audience restriction: Use targetInstance to prevent token replay at unintended services.
  • Key rotation: Rotate signing keys periodically. When you rotate, update the well-known endpoint and notify trusted instances.
  • Discovery vs. pre-configuration: Discovery is convenient for dev, but pre-configure public keys in production for stronger security guarantees.
  • Auto-trust: autoTrust only skips the trusted-list check. Verification still needs a public key for the issuing instance, so in practice you still add each instance (with its key) via addTrustedInstance or trustedInstances. Do not rely on it in production.
  • Trust levels are enforced by the verifier: The source instance cannot override the target’s trust level setting. When the target marks the source limited, permissions containing write or admin are always stripped regardless of what the source claims.

Full example

Two services federating agents:

W3C DID identity

Ed25519-backed DIDs for agents. Federation tokens are signed with the instance’s own EdDSA key.

Verifiable credentials

Embed W3C Verifiable Credentials in federation tokens for offline proof.

Delegation

Delegate permissions within a single theAuth instance.

Multi-tenant

Isolate tenants within a single instance instead of federating.
Last modified on October 19, 2026