An EdDSA-signed compact token carrying what the platform observed about one actor at one moment: the Skoor, its band, the version, n, confidence and the reason ids. Unscored actors cannot be proved (409): there is no proof of a number that does not exist. The public key is published as a JWKS.
post/api/proofs/actor
Issue a signed proof for an actor
| Auth | Bearer + X-Operator |
|---|
| Operation | Proof · POST /api/proofs/actor |
|---|
Parameters
| Name | In | Type | Notes |
|---|
| tenant (optional) | query | string | Tenant slug. Optional: the bearer token already proves the tenant. Pass it to be explicit. |
| Idempotency-Key (optional) | header | string | 1–255 characters. A replay with the same body returns the stored status and body with Idempotent-Replayed: true; a different body under the same key is 409. |
Request body (application/json, required) · object
| Field | Type | Notes |
|---|
| type | "entity" | "counterparty" | "agent" | |
| id | string | |
Responses
201 — A 24-hour EdDSA token, its claims, and where the public key lives. object
| Field | Type | Notes |
|---|
| token | string | Compact JWT (header.payload.signature), alg EdDSA. |
| claims | ProofClaims | |
| jwksUrl | string | |
400 — type (entity|counterparty|agent) and id required. Error
| Field | Type | Notes |
|---|
| error | string | What went wrong, in one sentence. |
| requestId (optional) | string | Present once the gateway is live: the X-Request-Id of the failed request. |
401 — Bearer token missing or unknown. Error
| Field | Type | Notes |
|---|
| error | string | What went wrong, in one sentence. |
| requestId (optional) | string | Present once the gateway is live: the X-Request-Id of the failed request. |
404 — No Skoor on record for the actor. Error
| Field | Type | Notes |
|---|
| error | string | What went wrong, in one sentence. |
| requestId (optional) | string | Present once the gateway is live: the X-Request-Id of the failed request. |
409 — The actor is unscored; a proof is never issued for a null Skoor. Error
| Field | Type | Notes |
|---|
| error | string | What went wrong, in one sentence. |
| requestId (optional) | string | Present once the gateway is live: the X-Request-Id of the failed request. |
Example
curl -s -X POST "https://skoor.ai/risk/api/proofs/actor?tenant=demo" \
-H "Authorization: Bearer test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Operator: you@bank.example" \
-H "Content-Type: application/json" \
-d '{"type":"entity","id":"enti_sim_acme"}'
get/api/proofs/verify
Verify a proof
Checks the signature against the platform key, the expiry and the presence of a Skoor. No database access; anyone may call it.
| Auth | None (public) |
|---|
| Operation | Proof · GET /api/proofs/verify |
|---|
Parameters
| Name | In | Type | Notes |
|---|
| token (optional) | query | string | The compact token. |
Responses
200 — valid with the claims, or invalid with the reason. ProofVerification
| Field | Type | Notes |
|---|
| valid | boolean | |
| reason (optional) | string | malformed | unsupported alg | unknown kid | bad signature | expired | no skoor in claims | token required |
| claims (optional) | ProofClaims | |
| expired (optional) | boolean | |
400 — token required. ProofVerification
| Field | Type | Notes |
|---|
| valid | boolean | |
| reason (optional) | string | malformed | unsupported alg | unknown kid | bad signature | expired | no skoor in claims | token required |
| claims (optional) | ProofClaims | |
| expired (optional) | boolean | |
Example
curl -s "https://skoor.ai/risk/api/proofs/verify?token=eyJhbGciOiJFZERTQSIs%E2%80%A6"