[a]authored byinflow
Agent quick start

Obtain a session credential

After enrollment, an Agent can request an optional credential for later protected-resource requests. First check what the Service issues and what the resource accepts.

Decide whether to request one

A session credential lets the Agent authenticate later requests without signing a new client assertion for each protected-resource request. It is not required to complete enrollment. If the Agent already has a valid credential that the intended resource accepts, it can use that credential instead of calling Grant again.

AEP command endpoints accept the baseline client assertion even when the Service does not advertise aep-jwt for protected resources. Grant and Revoke always require that assertion; a session credential cannot authenticate either command. To use a client assertion directly on a protected resource, the Service must separately advertise aep-jwt as an authentication method.

Choose a method the resource accepts

Read Inspect before requesting a credential. commands.supported must include grant, and commands.grant_types must include a type the Agent can use. Check authentication.methods separately: it lists methods accepted by the Service's protected resources. When the Service advertises OpenAPI, the operation's security requirements may narrow the choice further. An AEP challenge initiates discovery; it does not by itself select a credential type. Grant availability alone does not mean the key will work on every resource.

The example below chooses api-key only if the Service advertises it for Grant and the intended resource accepts it. A Service may instead issue basic or oauth-bearer. Each type defines different response fields and presentation rules; follow the API key, Basic, or OAuth Bearer guide for the selected type.

Ask the Service to issue the credential

Grant requires an existing enrollment recognized by the Service. If the Agent's current enrollment is uncertain, call Status before starting. Derive the Grant URL from the inspected http.endpoint_base; this example uses /aep/. Sign a fresh baseline assertion for the enrolled Agent with op=grant, and send a nonempty Idempotency-Key with the advertised grant type:

POST /aep/grant HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <jwt>
Idempotency-Key: 8709695d-6d79-49b4-a7ab-ae5636fed341

{"grant_type":"api-key"}

If a network failure leaves the outcome unknown, retry the same command and body with the same idempotency key, but sign a fresh assertion. The Service returns its cached or equivalent success for that request. Reusing the key with a different command or body is a conflict; it is not a way to request a second credential.

Store the credential securely

The response shape depends on the grant type. An API-key Grant can return these illustrative values:

{
  "api_key": "aep_example_7Jm5xQ2pL9vN4sR8tW6yB3kZ0",
  "credential_id": "key_example_123",
  "expires_at": "2027-01-01T00:00:00Z",
  "header": "x-service-key"
}

Store the secret with the Service DID, expiry, credential_id, and the type-specific instructions needed to present it. The credential_id is a stable, Service-issued management identifier, not the secret sent to a resource. Do not log or display the secret. Keep any granted scopes returned by the Service rather than assuming it granted every requested scope.

Present it only as the type specifies

For this API-key example, send api_key in the returned x-service-key header on a resource that accepts api-key. Do not invent an Authorization scheme for it. Basic and OAuth Bearer credentials use their own defined presentation forms. Stop presenting a credential when it expires or is revoked, and never forward it across an origin-changing redirect.

On this page