Identity¶
Identity material and, more importantly, whether the issuer still stands behind it. A certificate is minted for ten years and its parent signature never expires, so possession proves nothing about current standing — only the status endpoint does.
GET /api/certificate/{id}¶
One identity's public certificate
Unauthenticated
Callable with no credential.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
id |
path | yes |
Responses
| Status | Meaning |
|---|---|
200 |
The identity's public material. |
404 |
No such resource, or the caller may not see it. |
Response fields
| Field | Type | Notes |
|---|---|---|
id |
string | |
name |
string | |
certificate |
string | |
fingerprint |
string | |
parentSignature |
string | |
domainAtIssue |
string | The domain this identity was issued under. |
GET /api/identities/{fingerprint}/status¶
Whether the issuer still stands behind an identity
Unauthenticated
Callable with no credential.
This server's signed, timestamped answer about one fingerprint. It is the piece a certificate cannot carry, and the only thing that distinguishes a current holder from one who was removed.
The answer is signed by the root key rather than trusted on TLS alone: the caller has already pinned that key through DNS, so the statement needs no separate trust in this endpoint and a proxy cannot rewrite it.
The payload is a JSON envelope whose first field is
type: identity-status-v1. That separator is load-bearing — without
it, a signature over a bare fingerprint would itself be a forged parent
signature, and this endpoint would be a signing oracle.
unknown is not revoked. A restored backup answers unknown about
identities that are perfectly valid, and a verifier must not treat the
two the same.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
fingerprint |
path | yes | Lowercase hex SHA-256 fingerprint. |
Responses
| Status | Meaning |
|---|---|
200 |
A signed assertion. Cacheable for exactly as long as the signature claims validity, so a cache can never outlive the statement in it. |
400 |
Refused, with a named reason. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
payload |
string | Base64url JSON. Its first field is type: identity-status-v1, which is what stops the endpoint being a signing oracle. |
signature |
string | Root key signature over the payload. |
POST /api/verify-peer¶
Walk another server's trust chain
Unauthenticated
Callable with no credential.
Asks this server to verify a peer domain end to end — DNS TXT, served root key, and the peer's own answer about the identity's standing.
Request body
application/json
| Field | Type | Notes |
|---|---|---|
domain |
string |
Responses
| Status | Meaning |
|---|---|
200 |
The verdict. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
GET /api/challenges/{scope}/{slug}¶
Issue a handshake nonce
Unauthenticated
Callable with no credential.
Returns a single-use nonce to sign when a share or request requires a
proven identity, when an attestation offer is accepted (scope
attestation, with the offer's token as the slug), or when a
credential is moved to another identity (scope reissue, with the
fingerprint of the identity it is bound to as the slug and the
identity it moves to as identityId). The signature is submitted
with the resolve, the response, the claim or the reissue; a spent
nonce is refused.
Parameters
| Name | In | Required | Notes |
|---|---|---|---|
scope |
path | yes | Which kind of grant the challenge is for. |
slug |
path | yes | |
identityId |
query | yes | The identity that will sign the nonce. The nonce is bound to it. |
Responses
| Status | Meaning |
|---|---|
200 |
A nonce to sign. |
400 |
challenge_scope_invalid or challenge_identity_required. |
429 |
Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced. |
Response fields
| Field | Type | Notes |
|---|---|---|
nonce |
string | |
expiresAt |
string | |
algorithm |
string (RSA-SHA256 | ECDSA-P256-SHA256) |
How the identity's key signs: PKCS#1 v1.5 or ASN.1 DER ECDSA, both over the SHA-256 of the nonce. Absent when the identity is not held on this server. |