Account & access

Two related surfaces live here: self-service /me/* endpoints for managing your own account, and access administration for managing roles, permissions, and members across a namespace. See Authentication for how to obtain a token and Permissions, entitlements, and flags for how roles and permissions compose.

Concept

Manage your own account

# Full account bundle — identity, profile, consent, prefs, subscription
curl -sf "https://api.falcata.io/api/v1/me" -H "Authorization: Bearer $FURNACE_PAT" | jq '.data'

# Rename yourself
curl -sf -X PATCH "https://api.falcata.io/api/v1/me/profile" \
  -H "Authorization: Bearer $FURNACE_PAT" -H "Content-Type: application/json" \
  -d '{"name": "New Name"}'

# Check what you can do in a namespace
curl -sf "https://api.falcata.io/api/v1/me/permissions?namespace=marozzo" \
  -H "Authorization: Bearer $FURNACE_PAT" | jq '.data.permissions'

Manage notification and marketing preferences

# Mute one notification type (opt-out model — a missing key means enabled)
curl -sf -X PATCH "https://api.falcata.io/api/v1/me/notification-prefs" \
  -H "Authorization: Bearer $FURNACE_PAT" -H "Content-Type: application/json" \
  -d '{"type": "comment.reply", "enabled": false}'

# Withdraw marketing email consent
curl -sf -X PATCH "https://api.falcata.io/api/v1/me/email-consent" \
  -H "Authorization: Bearer $FURNACE_PAT" -H "Content-Type: application/json" \
  -d '{"emailSubscribed": false}'

Revoke your current token

curl -sf -X DELETE "https://api.falcata.io/api/v1/auth/token" \
  -H "Authorization: Bearer $FURNACE_PAT"

This revokes the token making the call — there's no endpoint to revoke someone else's PAT from the API; that stays a self-service action in the account UI.

Administer roles and permissions

Role writes need manage:roles (define/delete a role) or assign:roles (assign/revoke a role, grant/revoke a direct permission) in the target namespace. Granting anything that implies manage:roles additionally needs manage:roles.

# Define a role
curl -sf -X POST "https://api.falcata.io/api/v1/access/roles" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appNamespace":"marozzo","roleName":"editor","permissions":["edit:content","publish:content"],"description":"CMS editor"}'

# Assign it to a user
curl -sf -X POST "https://api.falcata.io/api/v1/access/roles/editor/assign" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appNamespace":"marozzo","userSubject":"sub_alice"}'

# Grant a one-off permission without a role
curl -sf -X POST "https://api.falcata.io/api/v1/access/users/sub_alice/permissions" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appNamespace":"marozzo","permission":"read:analytics"}'

Look up who has access

# A user's roles + permissions in one call
curl -sf "https://api.falcata.io/api/v1/access/users/sub_alice/bundle" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

# Everyone holding a given role
curl -sf "https://api.falcata.io/api/v1/access/roles/editor/members" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

List members and PATs

# Member growth over the last 30 days
curl -sf "https://api.falcata.io/api/v1/access/members/stats?days=30" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

# All PATs (requires api:admin — key values are never returned, only hashes)
curl -sf "https://api.falcata.io/api/v1/access/pats" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

Everything else — bans, auth-event history, subscriber grants, and GDPR export — in the full reference.