API Specification - Ringspace Trusted Webrings: Protocol Specification

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

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