Skip to content

Authentication

Overview

The API uses Clerk for user identity on the official Simple Feature Requests web apps. First-party and custom clients send a session token (JWT) on each GraphQL request in the Authorization header. The API verifies the token and resolves the current user for permission checks.

Whoever hosts the API configures Clerk and related secrets on the server side. As an API client or integrator, you only need a valid session token from the same Clerk application (or equivalent) that your deployment uses—typically from getToken() in the Clerk browser SDK or your backend’s session.

Sending the token

Send the session token in the Authorization header:

Authorization: Bearer <session_token>

For GraphQL requests:

curl -s -X POST "$BASE_URL/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{"query":"query { teamsForCurrentUser { id name } }"}'

Current user and personal team

  • The API maps the JWT sub claim (Clerk user ID) to an internal user record.
  • On first sign-in, a personal team is usually created for the user; they are added as team admin. Their own projects can live in that team.
  • The resolved user drives authorization for mutations and protected queries.

Public and optional auth

  • Public — No token required. Used for: hello, and (when applicable) read access to public projects and their boards (boards, requests on those boards, statuses for those boards, tags, comments, attachments, vote counts — subject to resolver rules).
  • Optional auth — Token optional for many read operations on public data, and for createRequest on public boards/projects when anonymous submission is allowed. If the caller sends a token, the request is typically owned by that user; if not, the request may be anonymous and only admins can change it per permissions rules.
  • All other operations require a valid token and a resolved current user.

Permissions (summary)

  • Team roles: admin (full team control; can act on any project/request/comment in the team without being a project member), member (can create projects and view team).
  • Project roles: admin (full project control; update/lock requests, hide comments, manage statuses/tags/members), member (create requests, comment, vote, edit own request/comment).
  • Request ownership: The user who submitted the request can edit title/description only, and only while the request is not locked. Status changes (updateRequest with statusId, setRequestStatus) and lock/unlock (lockRequest) are restricted to project admins, team admins, and super admins. Admins can also edit or delete a request after it has been locked. Owner edit/delete on a locked request returns This request is locked and cannot be edited. / ... cannot be deleted..
  • Comments: Author can edit/delete own comment. Project admin or team admin can hide comments (setCommentHidden) and delete any comment.
  • Project deletion: Soft/archive only — set archivedAt via updateProject; archived projects are excluded from default listing; project/team admins can list with includeArchived and restore by clearing archivedAt.
  • Public projects: If a project is not private (isPublic = true), anyone can submit a request (with or without logging in). Anonymous requests have no owner; only project/team admins can update them.

Operation-level auth behavior matches the deployed GraphQL schema and server rules; use introspection or your provider’s reference for edge cases.