Revoke credentials
Stop using a credential before you revoke it
Revoke is useful when a credential may have been exposed, the Agent no longer needs it, or the Owner wants to retire a group of credentials. Stop presenting the affected secret as soon as you decide to revoke it. Removing a local copy only affects that installation; the Service must invalidate its issued credential through Revoke.
Read Inspect first. The Service must advertise revoke in commands.supported. A session credential cannot authenticate the Revoke command, including when that same credential is the target. The Agent uses its baseline client assertion instead.
Choose the smallest supported scope
Revoke affects credentials issued to the authenticated Agent, not another Agent's credentials. The request body selects one of these alternatives; do not send all three in sequence:
| Target | Request body and availability |
|---|---|
| One credential | {"grant_type":"api-key","credential_id":"key_example_123"}. Use this only when commands.grant_types_config.api-key.supports_per_credential_revoke is "true". The selected grant type may define further targeting requirements. |
| One grant type | {"grant_type":"api-key"}. Revokes every API-key credential issued to this Agent. Use an advertised grant_type; this form does not require per-credential support. |
| Every grant type | {"all_grant_types":"true"}. A Service that supports Revoke must support this form. all_grant_types is a string boolean and cannot be combined with grant_type or credential_id. |
If per-credential support is absent or "false", do not guess that a credential_id will work. Use the grant-type or all-grant-types form according to the intended effect. The ID is the stable management identifier returned by Grant, not the secret presented to a resource.
Send an authenticated Revoke request
Derive the URL from Inspect's http.endpoint_base. This example uses /aep/ and targets one API key because the Service advertised per-credential support. Sign a fresh client assertion with op=revoke and send a nonempty Idempotency-Key:
POST /aep/revoke HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <jwt>
Idempotency-Key: e997bf69-16b8-411e-8d73-80743435993a
{"grant_type":"api-key","credential_id":"key_example_123"}To use another scope, change only the JSON body to the matching alternative above and use a new idempotency key for that new operation. Never authenticate Revoke with a session credential, even if that credential works on a protected resource.
Handle success and an uncertain result
A successful Revoke returns 200 OK with {}. The same success is returned when no matching credential existed, so it does not prove that a specific credential was present. After success, remove the affected local secrets and associated presentation metadata. Keep unrelated credentials when the request targeted only one credential or one grant type.
If the response is lost, keep the affected credentials out of use and retry the identical command and body with the same idempotency key and a fresh assertion. Do not infer success from a timeout, and do not choose a broader scope merely to resolve uncertainty. A changed body with the same key is an idempotency_conflict. For the complete command and failure contract, see Grant and Revoke. For the preceding Agent flow, see Obtain a session credential.
