API Reference

API Reference — All 11 Endpoints

Base URL: https://identity.sentryagent.ai

All POST requests use Content-Type: application/json.

GET /v1/health

Returns service health status.

Auth: None

Response:

{ "status": "ok", "version": "1.0.0" }

GET /v1/did

Returns the identity_bridge's own DID document.

Auth: None

Response: DID document (W3C format). See DID Document.

POST /v1/auth/verify-phone

Step 1 of registration. Submits a Developer Manifest and initiates phone verification.

Auth: None

Request body:

Field	Type	Required	Description
manifest	object	Yes	Developer Manifest — see Manifest Schema

Response:

Field	Type	Description
manifest_session_id	string	UUID4 session token — pass to Step 2
public_profile	object	Sanitised profile (no phone number)

Errors: 400 (invalid manifest), 429 (rate limited), 503 (unavailable)

POST /v1/auth/confirm-manifest

Step 2 of registration. Confirms the manifest and triggers OTP delivery.

Auth: None

Request body:

Field	Type	Required
manifest_session_id	string	Yes

Response:

Field	Type	Description
otp_session_id	string	UUID4 — pass as `session_id` to Step 3
expires_at	string	ISO8601 — session expires in 15 minutes

Errors: 410 (session expired), 429 (rate limited), 503 (unavailable)

POST /v1/auth/confirm

Step 3 of registration. Submits the OTP and issues the Agent Badge.

Auth: None

Important: The request body field is session_id, not otp_session_id. The value is the otp_session_id from Step 2.

Request body:

Field	Type	Required
session_id	string	Yes — value from Step 2's `otp_session_id`
otp	string	Yes — 6-digit numeric code

Response:

Field	Type	Description
verified	boolean	Always `true` on success
badge	string	Agent Badge JWT

Errors: 401 (wrong OTP), 410 (session expired), 429 (too many attempts), 503 (unavailable)

POST /v1/verify

Verifies an Agent Badge's cryptographic signature and returns the agent's public profile.

Auth: None

Request body:

Field	Type	Required
badge	string	Yes — Agent Badge JWT

Response:

Field	Type	Description
valid	boolean	true if signature valid and not revoked
did	string	Agent DID
public_profile	object	Agent public profile

POST /v1/sign

Signs a message using the agent's private key.

Auth: Authorization: Bearer + badge in request body

Request body:

Field	Type	Required
message	string	Yes
badge	string	Yes — same badge as Authorization header

Response:

Field	Type	Description
jws	string	JSON Web Signature
did	string	Signing agent DID
signed_at	string	ISO8601 timestamp

POST /v1/rotate

Rotates the agent's badge — issues a new badge and DID, invalidating the old one.

Auth: Authorization: Bearer + badge in request body

Request body:

Field	Type	Required
badge	string	Yes

Response:

Field	Type	Description
new_badge	string	Replacement Agent Badge JWT
new_did	string	New agent DID
rotated_at	string	ISO8601 timestamp

POST /v1/revoke

Permanently revokes an agent's badge. This operation cannot be undone. Latency ~10s (gRPC).

Auth: Authorization: Bearer + badge in request body

Request body:

Field	Type	Required
badge	string	Yes

Response:

Field	Type	Description
revoked	boolean	Always `true` on success

GET /v1/jwks

Returns the identity_bridge's JSON Web Key Set. See JWKS.

Auth: None

GET /v1/manifest/{did}

Returns the public profile for a given DID. See Manifest Lookup.

Auth: None