DEVELOPER DOCUMENTATION

Organisation API v1

Server-to-server verification requests for approved AstruVerify organisations.

Authentication

Create an application-scoped credential in the Developer Portal. Send it only from your server:

TEST: X-AstruVerify-Api-Key: av_test_...
LIVE: X-AstruVerify-Api-Key: av_live_...

The plaintext credential is shown once. AstruVerify stores its prefix and SHA-256 hash.

Create a verification

POST /api/v1/verifications
Content-Type: application/json
X-AstruVerify-Api-Key: av_test_...

{
  "citizenEmail": "sandbox-citizen@example.test",
  "purpose": "Customer identity verification",
  "requestedClaims": ["full_name", "over_18"]
}

Returns HTTP 201 Created with a requestId, citizen action URL and current status.

Check status

GET /api/v1/verifications/{requestId}
X-AstruVerify-Api-Key: av_test_...

External states are Pending, Verified, PartiallyVerified, Declined and Expired. Completed responses include the portable assertion.

Webhooks

Subscribe an application to one or more events:

  • verification.created
  • verification.completed
  • verification.declined
  • verification.expired
  • verification.fraud_reported

Each POST includes:

X-AstruVerify-Event: verification.completed
X-AstruVerify-Delivery: <delivery-id>
X-AstruVerify-Environment: test
X-AstruVerify-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Verify the signature over the exact string {timestamp}.{raw-json-body} using your webhook signing secret. Reject stale timestamps and compare signatures in constant time.

Strict mode boundary: TEST keys can use only synthetic TEST citizens created for your organisation and TEST providers. LIVE keys can use only normal citizen accounts and LIVE providers. Legacy vsa_sk_… keys are TEST-only. LIVE mode is disabled by default.