Invites

Experimental

This API is experimental and will change. See the Permissioned Spaces overview for context.

Invites let space creators distribute invite tokens without knowing recipients’ DIDs in advance.

HappyView extension

Invites are a HappyView-specific feature, not part of the atproto spaces spec.

Creating an invite

Only the space’s creator or an operator with superadmin can create invites.

TypeScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.createInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "at://did:web:happyview.example.com/space/com.example.forum/main",
    access: { read: true, write: true },
    maxUses: 10,
    expiresAt: "2026-06-01T00:00:00Z",
  }),
});
interface CreateInviteResponse {
  inviteId: string;
  token: string;
  access: { read: boolean; write: boolean };
  maxUses: number | null;
  expiresAt: string | null;
}
const data: CreateInviteResponse = await response.json();

JavaScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.createInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "at://did:web:happyview.example.com/space/com.example.forum/main",
    access: { read: true, write: true },
    maxUses: 10,
    expiresAt: "2026-06-01T00:00:00Z",
  }),
});
const data = await response.json();

Rust

let response = client
    .post("https://happyview.example.com/xrpc/dev.happyview.space.createInvite")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", &dpop_proof)
    .json(&serde_json::json!({
        "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
        "access": { "read": true, "write": true },
        "maxUses": 10,
        "expiresAt": "2026-06-01T00:00:00Z"
    }))
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

clientKey := "hvc_..."   // your API client key
accessToken := "..."     // DPoP access token
dpopProof := "..."       // DPoP proof JWT

body := bytes.NewBufferString(`{
  "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
  "access": { "read": true, "write": true },
  "maxUses": 10,
  "expiresAt": "2026-06-01T00:00:00Z"
}`)
req, err := http.NewRequest("POST",
  "https://happyview.example.com/xrpc/dev.happyview.space.createInvite", body)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl -X POST 'https://happyview.example.com/xrpc/dev.happyview.space.createInvite' \
  -H 'X-Client-Key: hvc_...' \
  -H 'Authorization: DPoP <token>' \
  -H 'DPoP: <proof>' \
  -H 'Content-Type: application/json' \
  -d '{
    "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
    "access": { "read": true, "write": true },
    "maxUses": 10,
    "expiresAt": "2026-06-01T00:00:00Z"
  }'

Input:

Field	Type	Required	Default	Description
space	string	Yes		The space this invite is for
access	object	No	{ "read": true, "write": false }	Access granted on acceptance: read and write booleans, both required when access is given
maxUses	integer	No	unlimited	Maximum number of times the invite can be redeemed
expiresAt	string (datetime)	No	never	When the invite expires, in UTC (ending in Z or +00:00)

Response (201):

{
  "inviteId": "uuid",
  "token": "a1b2c3d4e5f6...",
  "access": { "read": true, "write": true },
  "maxUses": 10,
  "expiresAt": "2026-06-01T00:00:00Z"
}

Caution

The token is only returned once. It is stored as a SHA-256 hash, so HappyView cannot recover the plaintext.

Accepting an invite

Any authenticated user can accept an invite token to join the space.

TypeScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.acceptInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: "a1b2c3d4e5f6...",
  }),
});
interface AcceptInviteResponse {
  uri: string;
  access: { read: boolean; write: boolean };
}
const data: AcceptInviteResponse = await response.json();

JavaScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.acceptInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: "a1b2c3d4e5f6...",
  }),
});
const data = await response.json();

Rust

let response = client
    .post("https://happyview.example.com/xrpc/dev.happyview.space.acceptInvite")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", &dpop_proof)
    .json(&serde_json::json!({
        "token": "a1b2c3d4e5f6..."
    }))
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

clientKey := "hvc_..."   // your API client key
accessToken := "..."     // DPoP access token
dpopProof := "..."       // DPoP proof JWT

body := bytes.NewBufferString(`{"token": "a1b2c3d4e5f6..."}`)
req, err := http.NewRequest("POST",
  "https://happyview.example.com/xrpc/dev.happyview.space.acceptInvite", body)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl -X POST 'https://happyview.example.com/xrpc/dev.happyview.space.acceptInvite' \
  -H 'X-Client-Key: hvc_...' \
  -H 'Authorization: DPoP <token>' \
  -H 'DPoP: <proof>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "a1b2c3d4e5f6..."
  }'

Response (201):

{
  "uri": "at://did:web:happyview.example.com/space/com.example.forum/main",
  "access": { "read": true, "write": true }
}

Acceptance fails if:

• The token is invalid (no matching hash found): 404
• The invite has been revoked: 400
• The invite has reached its maxUses: 400
• The invite has expired: 400
• The user is already a member of the space: 409

Revoking an invite

TypeScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.revokeInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "at://did:web:happyview.example.com/space/com.example.forum/main",
    inviteId: "uuid",
  }),
});

JavaScript

const response = await fetch("https://happyview.example.com/xrpc/dev.happyview.space.revokeInvite", {
  method: "POST",
  headers: {
    "X-Client-Key": CLIENT_KEY,
    "Authorization": `DPoP ${ACCESS_TOKEN}`,
    "DPoP": DPOP_PROOF,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "at://did:web:happyview.example.com/space/com.example.forum/main",
    inviteId: "uuid",
  }),
});

Rust

let response = client
    .post("https://happyview.example.com/xrpc/dev.happyview.space.revokeInvite")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", &dpop_proof)
    .json(&serde_json::json!({
        "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
        "inviteId": "uuid"
    }))
    .send()
    .await?;

Go

clientKey := "hvc_..."   // your API client key
accessToken := "..."     // DPoP access token
dpopProof := "..."       // DPoP proof JWT

body := bytes.NewBufferString(`{
  "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
  "inviteId": "uuid"
}`)
req, err := http.NewRequest("POST",
  "https://happyview.example.com/xrpc/dev.happyview.space.revokeInvite", body)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl -X POST 'https://happyview.example.com/xrpc/dev.happyview.space.revokeInvite' \
  -H 'X-Client-Key: hvc_...' \
  -H 'Authorization: DPoP <token>' \
  -H 'DPoP: <proof>' \
  -H 'Content-Type: application/json' \
  -d '{
    "space": "at://did:web:happyview.example.com/space/com.example.forum/main",
    "inviteId": "uuid"
  }'

Only the space’s creator or an operator with superadmin can revoke an invite. Revoking prevents future redemptions but does not remove members who already redeemed it. A revoke answers {"success": true}, and an inviteId that is not one of the space’s invites fails with 404.

Listing invites

Only the space’s creator or an operator with superadmin can list invites.

TypeScript

const response = await fetch(
  "https://happyview.example.com/xrpc/dev.happyview.space.listInvites?space=at://did:web:happyview.example.com/space/com.example.forum/main",
  {
    headers: {
      "X-Client-Key": CLIENT_KEY,
      "Authorization": `DPoP ${ACCESS_TOKEN}`,
      "DPoP": DPOP_PROOF,
    },
  },
);
interface Invite {
  id: string;
  access: { read: boolean; write: boolean };
  maxUses: number | null;
  uses: number;
  expiresAt: string | null;
  revoked: boolean;
  createdBy: string;
  createdAt: string;
}
const data: { invites: Invite[] } = await response.json();

JavaScript

const response = await fetch(
  "https://happyview.example.com/xrpc/dev.happyview.space.listInvites?space=at://did:web:happyview.example.com/space/com.example.forum/main",
  {
    headers: {
      "X-Client-Key": CLIENT_KEY,
      "Authorization": `DPoP ${ACCESS_TOKEN}`,
      "DPoP": DPOP_PROOF,
    },
  },
);
const data = await response.json();

Rust

let response = client
    .get("https://happyview.example.com/xrpc/dev.happyview.space.listInvites")
    .query(&[("space", "at://did:web:happyview.example.com/space/com.example.forum/main")])
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", &dpop_proof)
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

clientKey := "hvc_..."   // your API client key
accessToken := "..."     // DPoP access token
dpopProof := "..."       // DPoP proof JWT

req, err := http.NewRequest("GET",
  "https://happyview.example.com/xrpc/dev.happyview.space.listInvites?space=at://did:web:happyview.example.com/space/com.example.forum/main",
  nil)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

cURL

curl 'https://happyview.example.com/xrpc/dev.happyview.space.listInvites?space=at://did:web:happyview.example.com/space/com.example.forum/main' \
  -H 'X-Client-Key: hvc_...' \
  -H 'Authorization: DPoP <token>' \
  -H 'DPoP: <proof>'

Parameters:

Field	Type	Required	Description
space	string	Yes	The space to list invites for

Response:

{
  "invites": [
    {
      "id": "uuid",
      "access": { "read": true, "write": true },
      "maxUses": 10,
      "uses": 3,
      "expiresAt": "2026-06-01T00:00:00Z",
      "revoked": false,
      "createdBy": "did:plc:abc123",
      "createdAt": "2026-05-09T12:00:00Z"
    }
  ]
}

List responses carry the invite metadata and never the token.