[a]authored byinflow
Agent quick start

Check status

Ask the Service for your Agent's current enrollment state, then decide whether to proceed, satisfy a requirement, wait, or stop.

Read the existing enrollment

An Enroll response tells you the Service's decision at that moment. If it is pending, verification or other work may change the state later. Status reads the Service's current record for the authenticated Agent; it does not submit another enrollment or replace that record. Use it only when the Service advertises status in commands.supported.

This page continues the Enroll an Agent example. The Agent submitted contact.email to https://api.example.com; the Service returned pending because the email had not been verified and Owner action was needed. Check Status to learn what remains and whether the Service has made a new decision.

Send an authenticated Status request

Send a bodyless GET to the Status path derived from the inspected http.endpoint_base. The example base /aep/ gives /aep/status. Sign a fresh baseline client assertion for the same Agent and Service, with op set to status and a new jti. Do not reuse the Enroll assertion: it was bound to a different operation.

GET /aep/status HTTP/1.1
Host: api.example.com
Authorization: AEP <jwt>

Every exposed Status endpoint accepts the baseline assertion. A session credential is an additional possibility only when its concrete grant type allows Status; the example needs none. Status has no request body and does not need the idempotency key required for state-changing POST commands. The Agent identity and assertions guide covers assertion construction.

Read the Service's current state

A successful Status response uses 200 OK and one lifecycle status. The Service might still report the pending email and separate Owner action:

{
  "owner_action_required": "true",
  "status": "pending",
  "verification_pending": ["contact.email"]
}

After verification completes and the Owner acts, a later Status response can report active. When since is present, it gives the time of the last state transition, not the original Enroll request:

{
  "since": "2026-05-28T12:00:00Z",
  "status": "active"
}

These are the same Agent identity at two different moments. A new 200 OK response is not a fresh Enroll decision, and active does not authorize every application operation.

Separate verification, requirements, and Owner action

verification_pending names claims already submitted but not yet verified. requirements_pending names requirements the Agent still needs to satisfy. Neither list contains claim values; an absent list means there are no items in that category. Do not treat a submitted email awaiting verification as a missing requirement or send it repeatedly to try to clear the pending state.

owner_action_required is separate from both lists. Its string value true means the Agent's Owner must complete an out-of-band action before the identity can become or remain active. The Agent should surface that need to its Owner rather than attempting to satisfy it with another Status or Enroll request. Consult Enrollment lifecycle and Owner action for the full state model.

Choose the next action from the state

  • active: The Agent is enrolled and operational. It can continue to a protected operation if the Service advertises an authentication method for that resource; the application still decides authorization.
  • pending: Respond to any missing requirement or Owner action, and check Status again when the Service's decision may have changed. Do not treat the state as permission to proceed.
  • unavailable: Pause access while the Service reports a temporary, non-punitive unavailability. Do not use Enroll as a repair operation.
  • suspended: Stop access while the Service has temporarily disabled the identity. Resolve the Service action through its separate process; repeating Enroll does not lift it.
  • terminated: Stop using the identity; the Service has permanently de-registered it. A new Enroll request for that record is not a reset.
  • rejected: Stop this enrollment attempt. The Service reports that asynchronous verification failed; another Enroll request does not replace the existing record.

For an active identity, continue to Access a protected resource when the Service has advertised a method for that resource. For any state, the Enroll and Status page provides the complete lifecycle definitions.

Distinguish a state from an error

A 200 OK Status response with status equal to suspended reports a lifecycle state; it is not a 403 error. If the Agent then attempts an operation the Service blocks because of that state, the operation can receive a Problem Details error instead. Handle the error for that attempted operation without changing the meaning of the Status response.

A failed Status assertion can return the non-disclosing not_recognized error. Do not infer from it whether an Agent record exists or try to repair it by repeatedly enrolling. See Errors and idempotency for error responses and retry decisions.

On this page