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",
  "keyset": {
    "keys": [
      {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "HttCUXNxSVAtreslSl51Sa0Zb_8WVec6yMjXaDvkJic",
        "kid": "9d2cb51ae91c4eb4ae582d92b3b0b18abce52816d41211ab93a9d9faa7ed0b3a",
        "alg": "EdDSA",
        "use": "sig"
      }
    ]
  }
}

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_base64url",
    "old_key": "some_base64url",
    "member_url": "https://alice-zone.net"
  },
  "signature": "more_base64url"
}

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"
}