Agent Fleet Onboarding
For organizations running dozens or hundreds of AI agents, manually registering each agent and issuing individual API keys is impractical. Formael's fleet onboarding model uses your existing enterprise identity infrastructure to onboard agents automatically - without any per-agent credential distribution.
How It Works
Fleet onboarding combines two platform capabilities:
- Identity Federation - Formael trusts JWTs issued by your identity provider (Okta, Azure AD, Auth0, or any OIDC-compliant IdP) as valid agent credentials
- Provisioning Policies - When a federated token arrives from an agent not yet registered in Formael, a policy determines whether to create the agent automatically, queue it for review, or reject it
The result: an agent that already has an identity in your IdP can present its token to Formael and start submitting intents - no manual registration step required.
Step 1: Register an Identity Federation
In the Formael dashboard, navigate to Identity → Federations and create a new federation:
| Field | Description |
|---|---|
| Issuer URI | The iss value in your IdP's tokens (e.g., https://your-org.okta.com/oauth2/default) |
| JWKS URI | Where Formael fetches your IdP's public keys - auto-discovered via OIDC metadata if omitted |
| Audience | Expected aud claim (e.g., api://formael) |
| Subject claim | Which claim carries the agent identifier (sub, client_id, or a custom claim) |
| Default scope | Capabilities and resource limits applied to auto-provisioned agents from this federation |
Once registered, any JWT from this issuer that passes validation is a valid Formael credential.
Step 2: Configure a Provisioning Policy
Navigate to Agents → Provisioning Policies and configure how Formael handles unknown agents:
| Mode | Behavior |
|---|---|
AUTO_CREATE | Agent is automatically provisioned with the federation's default scope; the intent request proceeds without interruption |
REVIEW_QUEUE | Agent is queued for administrator review; the intent request is held until an administrator approves or denies the agent |
REJECT | Any agent not already registered is rejected outright; only pre-registered agents can authenticate |
Recommended starting configuration: Use REVIEW_QUEUE when first enabling a federation. This lets you see which agents are attempting to connect and validate that your claim mapping is working correctly before switching to AUTO_CREATE.
Step 3: Point Agents at Formael
Configure your agents to send their IdP-issued JWT to Formael. The token goes in the standard Authorization header:
Authorization: Bearer <idp-issued-jwt>The Formael gateway - whether REST API or MCP - accepts this token without any other configuration change. Agents do not need Formael-specific credentials.
For Kubernetes workloads: Use projected service account tokens with the Formael audience, configure OIDC federation with your cluster's issuer URI, and mount the token as an environment variable or file.
For Azure/AWS/GCP workloads: Use the cloud provider's OIDC token endpoint to generate a JWT with the Formael audience. No secrets to distribute.
Managing the Review Queue
When REVIEW_QUEUE is active, incoming agents appear in Agents → Provisioning Queue with their claimed identity and the timestamp of first contact.
For each queued agent you can:
- Approve - the agent is registered with the federation's default scope and the held intent is released
- Approve with custom scope - override the default scope before approving
- Deny - the agent is rejected and future requests from the same identity are blocked
The queue is also accessible via the Management API for teams that want to build automated triage workflows.
Switching to AUTO_CREATE
Once you've validated that your claim mapping is correct and your default scope is appropriately restrictive, switch to AUTO_CREATE to eliminate the approval step entirely. Agents are provisioned instantly on first contact.
Auto-created agents start in PROVISIONED state, transition to ACTIVE on their first successful intent, and can be reviewed or suspended at any time from the agent management console.
Agent Lifecycle at Scale
All agent state transitions are immutable and audited. For large fleets, the Management API provides bulk access:
- List all agents with filtering by state, federation source, environment tag, or last-seen date
- Suspend agents that show unexpected behavior
- Retire agents when a workload is decommissioned
Retiring an agent revokes all its credential bindings and seals its audit history. A retired agent's identity cannot be reused.
Default Scope and Per-Agent Customization
Agents provisioned from a federation start with the default scope configured on the provisioning policy. This scope sets:
- Which capability domains the agent can use
- Daily cost limits
- Rate limits
- Environment tag (
production,staging,development)
After provisioning, scope can be adjusted per-agent from the agent detail page. Tightening scope takes effect immediately; the change is audited.
Security Considerations
Claim binding: A federation is bound to a specific issuer URI. Tokens from any other issuer - even one with a similar configuration - are rejected.
Token validation: Every federated JWT undergoes 8-point validation: issuer, audience, algorithm allowlist, expiry, not-before, JWKS signature, claim presence, and claim format. Tokens that fail any check are rejected with no fallback.
Scope intersection: Even if a federated token presents broad claims, the agent's configured scope is the ceiling. A token cannot elevate an agent's permissions beyond what an administrator has authorized.
Provisioning rate limiting: To prevent abuse, auto-provisioning is rate-limited per federation. Bursts of unknown agent registrations trigger an alert rather than creating agents without bound.