Ring Server API Specification

Authentication/Authorization

API requests are authenticated and authorized via pre-shared API keys

API Base

The base URL is /api

Server Information

GET /manifest

Retrieve the canonical manifest for the ring.

Validation

POST /member/validate

Performs validation checks for the given site. Takes the site’s manifest/signature as a body.

Returns a JSON object containing the validation status.

{ "result": "success" }

Standing

POST /member/standing

url: https://bobsawesomesite.com

Queries the ring for standing data. Returns a JSON object containing standing, vote breakdown, and anonymized descriptions.

{
  "standing": "Good"`
  "vote_split": {
    "good": 2,
    "bad": 0,
    "neutral": 1
  },
  "descriptions": [
    "Nice stuff here!",
    "Could be easier to read",
    "I like this site a lot"
  ]
}

Member Management

POST /member/invite/redeem

Redeems an invite code with data from the invitee to create a new Member record.

{
  "invite_code": "random-invite-code",
  "site_url": "https://example.com"
  "url": "https://alice-zone.net",
  "name": "Alice's Zone",
  "description": "A to Z Cryptography",
  "public_signing_key": "swfQMCUcf2fLEF6vfGCSnRBJTUiuRILYNmoZRnIdh0E="
}

Returns key data for the ring to the requester, upon join.

POST /member/rotate

Rotates a member’s public key. The request contains the URL, old key, the new key, and a signature of the request payload.

JSON body:

{
  "request": {
    "new_key": "some_base64==",
    "old_key": "some_base64==",
    "member_url": "https://alice-zone.net"
  },
  "signature": "more_base64=="
}

If rotation successul, returns:

{
  "result": "success"
}

POST /member/unenroll

Unenroll from a ring. The body is the member URL, and a signature of that payload.

{
  "request": {
    "member_url": "https://bobsawesomesite.com"
  },
  "signature": "base64_signature_of_request"
}

Success returns:

{
  "status": "unenrolled"
}