Build a social app
01 · Set up

Spin up a community + mint a Platform API Key.

Five minutes from zero to an authenticated `curl`. We'll provision Glow — a community we'll keep using through the rest of the guide — and a PAK with full agora.* scope on it.

1

Enable Agora on your workspace

Open the Agora area in the console and pick a workspace. If Agora isn't enabled, hit Enable Agora for this workspace(workspace owners only). Until it is, every Agora call returns 403 SERVICE_NOT_ENABLED.

2

Create your community

From the Agora landing page, click Create community. Give it a display name and a slug. For this guide we'll use Glow / glow as a small creator network. Leave Connect to a Heimdall app unchecked — standalone is the right default unless you already authenticate end-users via Heimdall.

The console call returns the new community's UUID. Keep it on your side — every call from here on takes it as:communityId.

response.json
{
  "id": "4d5f5c9e-b4ee-4401-9275-283feb66c178",
  "workspace_id": "<your-workspace-uuid>",
  "app_id": null,
  "slug": "glow",
  "display_name": "Glow",
  "description": "A tiny Instagram/LinkedIn-shaped community.",
  "settings": {},
  "status": "active",
  "created_by": "<your-platform-user-id>",
  "created_at": "2026-05-02T19:28:19.283Z",
  "updated_at": "2026-05-02T19:28:19.283Z"
}

3

Mint a Platform API Key (PAK)

Every customer-backend Agora call authenticates with a Platform API Key — a workspace-scoped opaque token prefixed pcft_live_. Mint one from Workspace settings → API keys, or via the API itself:

bash
# Replace <ws-slug> and <community-uuid>; swap your platform session
# cookie or PlatformUser bearer for Authorization.
curl -X POST https://api.auth.productcraft.co/v1/workspaces/<ws-slug>/api-keys \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <your-platform-session-token>" \
  -d '{
    "name": "Glow demo client",
    "description": "Full agora.* PAK for the build-a-social-app guide.",
    "policy": [{
      "effect": "allow",
      "actions": ["agora.*"],
      "resources": ["pcft:agora:community/<community-uuid>"]
    }]
  }'

# response (the plaintext token is returned ONCE — store it now):
# {
#   "token": "pcft_live_...",
#   "record": { "id": "...", "token_prefix": "pcft_live_YPs3yd", ... }
# }

Wildcard the policy as narrowly as makes sense. agora.* on a singlepcft:agora:community/<uuid> resource is fine for a server-side process. If you front your API with multiple workers, mint one PAK per service so a leak blast-radius is bounded.

4

Make your first call

Sanity-check the PAK by listing the (currently empty) actors collection on the community:

bash
curl -H "Authorization: Bearer pcft_live_..." \
  "https://agora.productcraft.co/v1/communities/<community-uuid>/actors?limit=10"

# response:
# {
#   "data": [],
#   "pagination": { "next_cursor": null, "has_more": false }
# }

If you get a 200 with an empty list, you're done. Wrong PAK → 401. Wrong scope → 403. Wrong community UUID → 404 (opaque — the response doesn't reveal whether the community exists in another workspace).

Next · Profiles →