Skip to main content
Forge Agent Identity gives an autonomous workload a durable organization-owned identity without treating registration as provider authority. Open Identities → Agents to create identities, enroll runtimes, and manage their access.

​
Identity, authenticator, and provider credential

These objects have different lifetimes and scopes: Forge stores the enrollment public key, not the runtime private key. Setup, runtime, and provider tokens are returned only for the delivery that creates them and must never be written to logs.

​
Registration and enrollment

An Agent identity records its accountable owner, optional owning group, purpose, tags, lifecycle, and optional inventory relationship. Creating it does not create a provider principal, credential, grant, or enrollment. Each runtime enrolls independently:
  1. Create an enrollment for the Agent identity.
  2. Copy the one-time setup token when Forge displays it.
  3. The runtime generates an EC P-256 key pair and exchanges the token with its public key.
  4. Forge consumes the short-lived token atomically and stores no private key or recoverable setup token.
The runtime signs establishment and later token requests with ES256 over the canonical request. Requests include the enrollment ID, timestamp, unique nonce, proof version, proof type, and signature. The proof window is five minutes and nonces cannot be replayed. Rotate the P-256 authenticator under the same enrollment when the local private key changes. A consumed, expired, revoked, or mismatched setup token cannot be replayed. Revoke one enrollment to remove one runtime. Disabling the Agent identity revokes all pending and active enrollments. Re-enabling it restores only the registration; create new enrollments for runtimes that should return.

​
Agent access

Select Manage agent access to configure each connected provider. Provider setup is separate from the inventory connection because discovery and mutation are different authorities. AWS, Azure, Google Cloud, and GitHub profiles are isolated from one another. Forge activates an access limit only after exact provider or broker readback matches its desired configuration. A stale or mismatched readback blocks new issuance without changing the saved profile.

​
Provider credential lifetimes

The assignment profile can reduce a configurable TTL but cannot exceed its integration ceiling or the provider maximum. Disabling an assignment blocks new issuance; an already delivered credential can remain usable until its native expiry.

​
Create and enroll

In the console:
  1. Open Identities → Agents and select Create Agent identity.
  2. Choose an accountable owner, enter the workload purpose, and add operational tags. Linking an inventory agent is optional and does not grant access.
  3. Open the identity, enter a runtime name under Runtime enrollments, and select Enroll.
  4. Select Copy setup JSON to copy the enrollment ID, one-time setup token, expiry, and establishment endpoint together. Deliver the package to that runtime through your existing secret-delivery channel, then clear the one-time display.
  5. Confirm the enrollment becomes Active after the runtime exchanges the token with its generated P-256 public key.
The enrollment list continues to show and copy the stable enrollment ID. While an enrollment is pending, it also shows and copies the establishment endpoint. This makes an older pending enrollment usable when its one-time token was already saved elsewhere. Forge cannot recover a token that was not saved; revoke that enrollment and create a new one. Programmatic registration uses the organization management API:
Create a one-time enrollment setup package with:
The response contains enrollment.id, plus a self-contained setup package with setup.enrollmentId, setup.setupToken, setup.expiresAt, and setup.establishEndpoint. The establishment endpoint is an API path relative to the same Forge API origin used to create the enrollment. Management endpoints require an authenticated organization session and the Agent Identity management permission. They are not currently part of the stable public headless API; contact Forge before building long-lived automation against them. The runtime then generates its own EC P-256 key pair and sends the setup token and public JWK to the returned establishment endpoint. It must retain the private key locally. Later it requests a runtime bearer token from POST /api/v1/agent-identity-runtime/token using a fresh signed proof. Never copy a private key from one runtime to another; create another enrollment.

​
Keyless provider access

Where supported, Forge uses workload federation instead of storing a long-lived provider key. Guided setup creates a dedicated operator or broker trust for the exact issuer, audience, subject, provider scope, and allowed permissions. Use the generated validation artifact to read the trust and permission boundary back from the provider. Access profiles do not silently expand when their limit changes. Create a new immutable revision, review the affected assignments, explicitly apply it, and confirm provider readback.

​
Review and containment

The Agent drawer separates enrollment state, provider assignments, activity, and lifecycle actions. Disabling an Agent identity prevents new Forge authentication and issuance, but already issued provider credentials can remain valid until provider expiry or revocation. Use the provider access and activity sections to confirm containment.

​
Troubleshooting

Use a distinct enrollment per runtime instance, rotate authenticators without changing the stable enrollment when possible, and revoke abandoned enrollments instead of deleting audit history.