Registration Flow

Registration Flow — 3 Steps

Registering an agent issues an Agent Badge JWT and a DID. The flow is:

Step 1 → Submit manifest + phone → receive manifest_session_id

Step 2 → Confirm manifest → receive otp_session_id + OTP on phone

Step 3 → Submit OTP using session_id (not otp_session_id) → receive badge

Field name note: Step 2 returns otp_session_id. Step 3 expects the same value in the session_id field. This is a known API quirk — the values are identical, only the key name differs.

Step 1 — Submit Manifest

curl -X POST https://identity.sentryagent.ai/v1/auth/verify-phone \
  -H "Content-Type: application/json" \
  -d '{
    "manifest": {
      "mobile_phone": "+15005550006",
      "trust_tier": "community",
      "agent_name": "My AI Agent",
      "agent_version": "1.0.0",
      "developer_name": "Acme Corp",
      "contact_email": "dev@acme.com",
      "primary_goal": "Customer support automation",
      "tools": ["web-search", "email"],
      "compliance_attestation": true,
      "data_residency": "us-east-1"
    }
  }'

Response:

{
  "manifest_session_id": "a3f7c821-...",
  "public_profile": {
    "agent_name": "My AI Agent",
    "agent_version": "1.0.0",
    "developer_name": "Acme Corp",
    "contact_email": "dev@acme.com",
    "primary_goal": "Customer support automation",
    "tools": ["web-search", "email"],
    "trust_tier": "community",
    "data_residency": "us-east-1"
  }
}

Save manifest_session_id for Step 2.

Step 2 — Confirm Manifest

curl -X POST https://identity.sentryagent.ai/v1/auth/confirm-manifest \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_session_id": "a3f7c821-..."
  }'

Response:

{
  "otp_session_id": "b9d2e445-...",
  "expires_at": "2026-06-01T12:15:00.000Z"
}

An OTP is now sent to the phone number in the manifest. The session expires in 15 minutes.

Save otp_session_id for Step 3 — but send it as session_id (see note above).

Step 3 — Confirm OTP

The field name in the request body is session_id, not otp_session_id.

curl -X POST https://identity.sentryagent.ai/v1/auth/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "b9d2e445-...",
    "otp": "123456"
  }'

Response:

{
  "verified": true,
  "badge": "eyJhbGciOiJFZERTQSIs..."
}

The badge JWT is your Agent Badge. Store it securely — it is needed for sign, rotate, and revoke operations.

Error Codes

Code	Meaning	Action
400	Invalid request / manifest	Check your input fields
401	Wrong OTP	Try again (retry limit applies)
410	Session expired	Start registration again
429	Too many attempts	Start registration again
503	Service unavailable	Retry after a moment