Session credentials

Why use a session credential?

The baseline way to authenticate an AEP command is a short-lived client assertion signed by the Agent. A Service may also issue a session credential after enrollment so its protected resources can use an existing API-key, Basic, or Bearer authentication system. For the Agent, this avoids signing a new assertion on every eligible resource request. The tradeoff is a reusable secret that must be stored, presented only to its issuing Service, and retired when it expires or is revoked.

A session credential is optional. A Service can use AEP without issuing one. When it does issue credentials, Grant creates them and Revoke invalidates them. Both commands always require a fresh baseline client assertion with the matching operation; an issued session credential cannot authenticate Grant or Revoke. Other AEP commands may also accept an issued credential when its grant type allows that use.

Read the two advertisements separately

The Service's Inspect document answers two different questions. commands.grant_types identifies the credential formats the Service can issue through Grant and invalidate through Revoke. Grant must also appear in commands.supported before the Agent invokes it. authentication.methods identifies, in Service preference order, the methods its protected resources accept. A credential is useful for a protected request only when that resource accepts its method and the Agent can satisfy the request's authorization requirements.

Every authenticated AEP command accepts its own operation-bound baseline assertion. That rule does not make aep-jwt a protected-resource method: the Service must advertise it in authentication.methods for that use. Conversely, advertising a grant type does not by itself say that a particular resource accepts the resulting credential. If Inspect does not advertise a usable method for the resource, the Agent must not guess one.

Choose a credential type

Choose among the grant types the Service advertises and the Agent can present. Each type has its own Grant response and protected-resource presentation rules; these pages show the exact fields and headers:

Store and manage the credential

After a successful Grant, the Agent stores the secret with its Service DID, grant type, expiry, granted scopes when present, and Service-issued credential_id. The ID is an opaque management identifier, unique across that Service's issued credentials; it is not the secret sent to a protected resource. For an API key, the Grant response selects the presentation header; the Agent must not guess a default.

Check the returned expiry and any granted scopes before use. Requested scopes are not a promise of what the Service granted, and the absence of a scope list is not a promise that every application action is authorized. Do not send an expired credential, put a credential in logs, or carry it to another origin on a redirect. The Service still decides whether the authenticated Agent may perform each application action. If the Agent needs another credential after expiry, it calls Grant again with a new baseline assertion.

End the credential's use

An Agent should discard an expired credential locally. If a credential may have been disclosed, or access should end sooner, call Revoke using a fresh baseline assertion. The Service always supports revoking all credentials of an advertised grant type and all grant types at once. Revoking one credential_id is available only when the Service advertises supports_per_credential_revoke as "true" for that grant type. Removing a locally stored secret alone does not revoke it at the Service.

• Grant and Revoke: Read the request and response contract.
• Session credentials example: Trace issuance, presentation, and revocation in one exchange.