OpenAgentID documentation
Start here

Integration practices

Small trust boundaries, explicit provider wiring, and useful failure evidence.

Start with the action

Decide whether the action needs identity, a capability, privileged authority, a provider credential, or several of these. Verify the required contract at the execution boundary rather than assuming another layer already did it.

Configure trust explicitly

Keep trusted issuer keys, audience, tenant policy, required scopes, resolver/anchor selection and supported algorithms under server control. A token or document is input to verification, not configuration for the verifier.

Choose custody for the actual runtime

Use appropriate secret storage and protect recovery material. Seed-file helpers store raw material; managed-language objects do not provide a universal zeroization guarantee. Record the exact key-derivation implementation and dependencies before relying on restoration. See key management.

Bound delegated access

Grant the minimum scope/lifetime needed, enforce parent attenuation, and configure revocation propagation and cache invalidation. Rotation schedules and token TTLs depend on the threat model and implementation; these docs do not prescribe a universal timer.

Preserve failure distinctions

Distinguish invalid input, unsupported version, failed signature, expired token, wrong audience/scope, missing provider configuration and unavailable authority evidence. All denial paths must keep the action from executing. Sanitize external errors and never log secrets.

Verify the actual deployment

Source review, parser/type checks, local examples, conformance runners and live user journeys prove different things. Record the relevant revision, feature flags, dependencies and results. Run negative cases and replica/restart behavior as well as a successful request.

On this page