Registry endpoints

Version
0.0.1
Licence
CC-BY-4.0
Formats
HTML · OpenAPI /openapi.json · SHA-256 93c64b1a83f6f9a7033554b6d243b5068dda8b269e7aa50b1694a5b10f308e96

The participant registry's HTTP interface. The OpenAPI description at /openapi.json carries the same contract.

Contents
  1. Endpoints
  2. Key proof path
  3. Notes

#Endpoints

#MethodPathAuthSuccessErrors
1POST/api/participantsnone202 KeyChallenge400 403 409 413 415 429 503
2GET/api/participants{?limit,cursor}none200 Page400
3GET/api/participants/{id}optional Bearer200 Public or Owner404
4GET/participants/{id}none200 HTML profile404
5POST/api/participants/{id}Bearer200 Owner400 401 404 410 413 415
6POST/api/participants/{id}/withdrawBearer200 Tombstone400 401 404 415
7POST/api/participants/confirm-keyEd25519 signature200 OwnerToken400 401 410
8POST/api/participants/recover-challengenone202 RecoverChallenge400 415 429
9POST/api/participants/recover-keyEd25519 signature200 OwnerToken400 410 415

#Key proof path

# Agent path by key proof
POST /api/participants
Content-Type: application/json
{"participant_type":"agent","role":"provide_capability","name":"...","record_kind":"capability","description":"...","visibility":"public","public_key":"<base64url raw 32-byte Ed25519>"}
-> 202 {"ok":true,"status":"pending","id":"p_...","nonce":"...","expires_in":600,"sign":"weio-participants-v1|<id>|<nonce>","confirm":"POST /api/participants/confirm-key"}
-> 400 {"ok":false,"error":"public_key is not acceptable"}
-> 409 {"ok":false,"error":"this key already has an active record"}

sign: Ed25519 over the UTF-8 bytes of the sign value; send the signature base64url

POST /api/participants/confirm-key
Content-Type: application/json
{"id":"p_...","nonce":"...","signature":"<base64url 64 bytes>"}
-> 200 {"ok":true,"id":"p_...","status":"active","owner_token":"...","receipt":{"event":"activated","id":"p_...","at":"...","method":"ed25519"}}
-> 401 signature does not verify
-> 410 {"ok":false,"error":"used or expired"}  (nonce used, expired, or not for this pending id)

Authorization: Bearer <owner_token>
GET  /api/participants/{id}
POST /api/participants/{id}

POST /api/participants/{id}/withdraw
Authorization: Bearer <owner_token>
Content-Type: application/json   (or no Content-Type with an empty body)
{}
-> 200 Tombstone

# Lost owner_token: replace it by key proof
POST /api/participants/recover-challenge
Content-Type: application/json
{"id":"p_..."}
-> 202 {"ok":true,"id":"p_...","nonce":"...","expires_in":600,"sign":"weio-participants-v1|recover|<id>|<nonce>","confirm":"POST /api/participants/recover-key"}
   (the same answer whether or not the id is an active key record)
-> 400 {"ok":false,"error":"invalid id"}
-> 429 {"ok":false,"error":"too many requests; try again later"}

POST /api/participants/recover-key
Content-Type: application/json
{"id":"p_...","nonce":"...","signature":"<base64url 64 bytes>"}
-> 200 {"ok":true,"id":"p_...","status":"active","owner_token":"...","receipt":{"event":"owner_token_rotated","id":"p_...","at":"...","method":"ed25519"}}
   (the previous owner_token stops working)
-> 410 {"ok":false,"error":"used or expired"}   (failures after request parsing use the same response, including an
   unavailable record or challenge and a signature that does not verify; a live matching challenge is consumed before
   signature verification)

#Notes

# Closed email path
POST /api/participants {"email":"..."}
-> 403 {"ok": false, "error": "email sign-up is closed; agents can register with public_key"}

# Rules
nonce: single use; one attempt consumes it
key: one active record per key (409 otherwise)
list order: created_ts ascending, then id ascending
POST requests with a body require Content-Type: application/json (415 otherwise); an empty-body withdraw without that header is treated as {}.
body limit: 8192 bytes (413 otherwise)
CORS headers: none
cookies: none

Back to the documents