Session credentials

The Agent is already enrolled with did:web:api.example.com. It fetches Inspect anonymously before requesting a credential. These are the fields relevant to this example, not a complete Inspect document:

{
  "authentication": {"methods": ["api-key"]},
  "commands": {
    "grant_types": ["api-key"],
    "grant_types_config": {
      "api-key": {
        "header_names": ["x-service-key"],
        "supports_per_credential_revoke": "true"
      }
    },
    "supported": ["enroll", "grant", "inspect", "revoke", "status"]
  },
  "http": {"endpoint_base": "/aep/"},
  "service": {"did": "did:web:api.example.com"}
}

commands.supported permits Grant and Revoke. commands.grant_types says the Service can issue API keys, while authentication.methods separately says its protected resources accept them. The grant-type configuration permits a later Revoke targeting one credential_id. The advertised header_names bounds what the Service may issue; the Grant response will select the actual header. The Agent still checks the intended resource's authentication requirements before sending a key.

The Agent signs a fresh baseline client assertion with op=grant and sends it to the Grant path derived from http.endpoint_base. It uses a nonempty idempotency key so an uncertain result can be retried safely:

POST /aep/grant HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <grant-assertion>
Idempotency-Key: 1de98c0e-599d-4d63-bfbb-a36554d5a2b6

{"grant_type":"api-key"}

The Service issues this illustrative key and tells the Agent how long it lasts and which header to use:

HTTP/1.1 200 OK
Content-Type: application/aep+json

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

The Agent stores api_key as a secret with the Service DID, expires_at, header, and credential_id. It does not present the management ID to a resource. At this point the Agent has one usable credential; it does not need another Grant for the next request. The values in this transcript are illustrative, not credentials to copy.

For a resource that accepts api-key, the Agent uses the exact header selected by Grant. It does not put this key into Authorization or invent an AEP API-key scheme:

GET /v1/reports/123 HTTP/1.1
Host: api.example.com
x-service-key: aep_example_7Jm5xQ2pL9vN4sR8tW6yB3kZ0

The Service can authenticate this request without a new client assertion. Application authorization still determines whether the Agent can read this particular report. The Agent must not forward the key to another origin or keep presenting it after expiry.

When the key is no longer needed, the Agent stops using it. Because Inspect advertised "supports_per_credential_revoke":"true", it can target the credential_id returned by Grant instead of revoking every API key. Revoke uses a new baseline assertion with op=revoke and a new idempotency key; the API key itself cannot authenticate this command:

POST /aep/revoke HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <revoke-assertion>
Idempotency-Key: c127db59-6894-4362-9b42-54b6b2877cec

{"grant_type":"api-key","credential_id":"key_example_123"}

The Service responds with an empty JSON object:

HTTP/1.1 200 OK
Content-Type: application/aep+json

{}

The Agent removes the key and its presentation metadata from local storage and never sends it again. A successful Revoke does not disclose whether a matching credential existed, but it does complete this requested revocation scope. If the response had been lost, the Agent would keep the key out of use and retry the same request body and idempotency key with a fresh assertion.

Use the guides for other choices

This transcript follows one API key and one targeted Revoke. For another credential type, follow its own response and presentation rules.

• Obtain a session credential: Understand when to call Grant.
• Revoke credentials: Choose grant-type or all-grant-types revocation when targeting one credential is unavailable or too narrow.