Agent Authentication

Every request to Formael must be made by a known agent identity. Formael supports two authentication methods: platform-issued API keys and federated JSON Web Tokens from your enterprise identity provider.

Agent Identity

An agent is a named, persistent identity registered in your Formael organization. Agents are not user accounts - they represent a specific AI workload (a pipeline, a background process, an LLM-powered service) that is authorized to submit intents.

Each agent has:

• A stable identity record - name, description, lifecycle state, and assigned scope
• One or more credential bindings - the actual authentication credentials associated with the agent
• A scope - the set of capabilities and domains the agent is permitted to act on

Authentication Methods

API Key Binding

The simplest method. You issue a platform-generated API key from the Formael dashboard under Agents → Credential Bindings, then bind it to an agent. Every request includes the key as a Bearer token:

Authorization: Bearer fml_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are best for:

• Development and testing
• Internal tooling and scripts
• Agents in controlled environments where key distribution is manageable

Keys can be rotated at any time. Rotation is instant - the old key stops working when a new binding is created.

Federated JWT (Enterprise Identity)

For enterprise deployments, agents can authenticate by presenting a JWT issued by your own identity provider - Okta, Azure AD, Auth0, or any OIDC-compliant IdP.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Formael validates the token against your registered IdP's JWKS endpoint and maps it to an agent identity using claim-based matching. No Formael-specific credentials need to be distributed to your agents.

Federated JWT is best for:

• Large agent fleets where managing individual API keys is impractical
• Workloads already using workload identity (Kubernetes service accounts, AWS IAM roles, GCP service accounts with OIDC tokens)
• Organizations that want centralized credential management through their IdP

Registering an Identity Federation

To use federated JWT authentication, register an Identity Federation in the Formael dashboard under Identity → Federations:

1. Issuer URI - the iss claim value from your IdP's tokens (e.g., https://your-org.okta.com/oauth2/default)
2. JWKS URI - where Formael fetches your IdP's public keys (auto-discovered from the issuer's .well-known/openid-configuration if omitted)
3. Claim mapping - which claim in the token carries the agent identifier (sub, client_id, or a custom claim)

After you save the federation, Formael generates two values:

• Audience (formael:fed:<id>) - copy this into your IdP's resource-server or application configuration as the accepted audience value. Your IdP will then issue tokens with this exact audience.
• Endpoint URL (https://api.formael.com/mcp/v1/f/<id>) - the dedicated MCP endpoint for this federation.

You do not choose the audience - Formael issues it and guarantees it is globally unique. This prevents any other organization from claiming your federation by registering the same issuer URL.

Formael caches your IdP's JWKS with automatic rotation detection. Token validation enforces issuer, audience, algorithm allowlist, expiry, not-before, and signature in that order.

Agent Scope

Every agent has a scope that defines its operational boundaries. The scope is enforced at the gateway - the agent cannot act outside it regardless of what the submitted intent requests.

Scope is configured per agent on the agent detail page. When using federated identity, the claim values from the JWT are intersected with the registered scope - a token cannot grant capabilities beyond what the agent is configured for.

Agent Lifecycle States

State transitions are immutable and audited. A RETIRED agent cannot be re-activated.

Auto-Provisioning for Agent Fleets

When a federated JWT arrives from an agent with no existing credential binding, Formael's provisioning policy determines what happens:

See Agent Fleet Onboarding for how to configure policies and manage the provisioning queue for large deployments.

Choosing an Authentication Method