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
How it works
The module only signs and verifies tokens, and it does not look agents up in your database. TheagentId, permissions and trust score you pass to issueFederationToken are exactly what the token carries.
- Service A issues a federation token for one of its agents
- The agent presents that token to Service B
- Service B fetches Service A’s public key from
/.well-known/theauth-federation.json - Service B verifies the token signature, checks expiry, and applies trust level rules
- Service B now has a
FederatedAgentobject with the agent’s identity and (possibly downgraded) permissions
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:sub: agent IDiss: source instance IDaud: target instance ID (if specified)exp: expiration timepermissions: agent permissions arraytrust_score: source instance’s trust assessment (0-1)delegation_scope: what the agent is allowed to delegatecredential: optional embedded Verifiable Credential JWT
Verifying federation tokens
Service B verifies the token:- Token signature matches the source instance’s public key
- Token has not expired
- Source instance is in the trusted list and has a public key configured
- Audience matches this instance (if audience is set in the token)
- 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.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:discoverInstance to fetch and parse this:
verify-only trust. You must explicitly upgrade the trust level after discovery.
Security considerations
- Short TTLs: Default is 5 minutes. Keep tokens short-lived to limit blast radius.
- Audience restriction: Use
targetInstanceto 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:
autoTrustonly 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) viaaddTrustedInstanceortrustedInstances. 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 containingwriteoradminare always stripped regardless of what the source claims.
Full example
Two services federating agents:- Service A (source)
- Service B (target)
Related
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.