API Reference

REST API for Prism — auth, OAuth, apps, teams, domains, GPG, public profiles, and admin endpoints.

API Reference#

Base path: /api

All endpoints return JSON. The web UI authenticates with a secure, HttpOnly session cookie. API integrations should use an OAuth access token from the standard authorization code flow, or a personal access token (prefix prism_pat_). Token-authenticated user endpoints are mostly under /api/oauth/me/*.

Cross-origin requests are only allowed from APP_URL, except for the image proxy, /.well-known/* and public profile endpoints, which are safe to embed. Request bodies are limited to 5 MiB; larger ones get 413.

Errors#

A failed request returns a stable, machine-readable code:

json
{ "error": "field_required", "params": { "field": "name" } }

error is a lowercase code such as team_not_found or forbidden; compare against it. params is present when the message has blanks to fill (a field name, a limit). The web UI translates each code, so there’s no English message in the response. Successful writes return data, or { "ok": true } when there’s nothing to return.

OAuth and OpenID Connect protocol endpoints (/api/oauth/token, /api/oauth/register, /api/oauth/userinfo, the device flow, and so on) follow their RFCs instead: error is the standard code and error_description is English text for client developers.

Init#

GET /api/init/status#

Returns { "initialized": false } until first-run setup is done.

POST /api/init#

Creates the first admin account. Only works before setup is complete.

json
{
  "email": "admin@example.com",
  "username": "admin",
  "password": "s3cur3",
  "display_name": "Admin",
  "site_name": "My Prism"
}

Response — { "user": { ... } }. The session is set in the cookie only.

Site#

GET /api/site#

Public site configuration for the frontend. No authentication; secrets are never included.

json
{
  "site_name": "Prism",
  "site_description": "...",
  "site_icon_url": null,
  "allow_registration": true,
  "invite_only": false,
  "captcha_provider": "none",
  "accent_color": "#0078d4",
  "initialized": true,
  "require_email_verification": false,
  "enable_public_profiles": true,
  "enable_sub_teams": true,
  "max_team_depth": 5,
  "enabled_sources": [
    { "slug": "github", "provider": "github", "name": "GitHub" }
  ]
}

The real response has more fields (feature switches and defaults).

Auth#

POST /api/auth/register#

json
{
  "email": "user@example.com",
  "username": "alice",
  "password": "hunter2",
  "display_name": "Alice",
  "captcha_token": "...",
  "invite_token": "..."
}

Include whichever bot-protection fields match the active captcha provider. invite_token is required in invite-only mode. Response — { "user": { ... } } when registration also signs the user in (the session is in the cookie only).

POST /api/auth/login#

json
{
  "identifier": "alice",
  "password": "hunter2",
  "totp_code": "123456",
  "captcha_token": "..."
}

identifier is a username, primary email, or (when allow_alt_email_login is on) any verified secondary email. totp_code is needed only if TOTP is enrolled. Passkeys use the dedicated endpoints below.

Response — { "user": { ... } }. If TOTP is enrolled but no code was sent:

json
{ "totp_required": true, "available_methods": ["totp", "passkey", "backup"] }

POST /api/auth/logout#

Ends the current session. Prism supports one browser session at a time; switching accounts means signing out and in again.

Returns { "ok": true, "next": "/login" }. Send the browser to next: when the session signed in to apps with SAML single logout, it’s /logout, which signs the user out of them first.

Email verification#

Endpoint
Purpose
GET /api/auth/verify-email?token=Verify using the emailed link
POST /api/auth/email-verify-codeGet an address to email for verify-by-sending: { "address", "code" }
POST /api/auth/check-email-verification{ "verified": boolean } — poll while the user sends the email
POST /api/auth/resend-verify-emailResend the link (accepts captcha fields)

TOTP#

All endpoints require authentication. A user can have several authenticators.

Endpoint
Purpose
GET /api/auth/totp/listList authenticators
POST /api/auth/totp/setupCreate a secret. Optional name. Returns { name, secret, uri }; uri is an otpauth:// URI
POST /api/auth/totp/verifyConfirm setup with the first code. Returns backup codes the first time any authenticator is added
DELETE /api/auth/totp/:idRemove one. Needs a TOTP code, backup code or passkey verification
POST /api/auth/totp/backup-codesRegenerate backup codes. Needs a valid TOTP code

Passkeys (WebAuthn)#

Endpoint
Purpose
POST /api/auth/passkey/register/begin / finishAdd a passkey
POST /api/auth/passkey/auth/begin / finishSign in. Pass username to narrow the credentials, or omit it
POST /api/auth/passkey/verify/begin / finishRe-verify while signed in (used by step-up confirmations)
GET /api/auth/passkeysList the user’s passkeys
DELETE /api/auth/passkeys/:idRemove one

GPG keys#

POST /api/auth/gpg-challenge#

Request a sign-in challenge: { "identifier": "alice" }. Returns { "challenge": "...", "text": "Prism login\n..." }. The site’s gpg_challenge_prefix is added to the text so users can recognise your site.

POST /api/auth/gpg-login#

Submit the gpg --clearsign-ed challenge:

json
{
  "identifier": "alice",
  "signed_message": "-----BEGIN PGP SIGNED MESSAGE-----\n..."
}

The challenge works once and expires after 5 minutes. If the account has TOTP and hasn’t turned off Require 2FA after GPG verification, the first call returns { "totp_required": true }; resubmit the same message with totp_code.

Managing keys#

GET, POST and DELETE /api/user/gpg[/:id] manage the signed-in user’s keys. POST takes an ASCII-armored public_key and optional name; RSA, EdDSA and ML-DSA keys are supported. A public_key holding several keys (concatenated blocks, or one block from gpg --export --armor key1 key2) is split into one key per entry, up to 20 distinct keys (400 gpg_too_many_keys beyond that). Repeated keys and keys already registered are skipped; with several keys, name gets a #1, #2… suffix. The response is { "keys": [...], "added": <count>, "skipped": <count> }, or 409 key_exists when every key was already there.

GET /users/:username.gpg is a public lookup that returns the user’s keys as armored blocks (application/pgp-keys).

With OAuth: GET /api/oauth/me/gpg-keys (gpg:read), POST and DELETE /api/oauth/me/gpg-keys/:id (gpg:write). POST splits keys the same way; its response also carries the first added key’s fields at the top level.

Sessions#

Endpoint
Purpose
GET /api/auth/sessionsThe user’s active sessions, with the IP and its geolocation
GET /api/auth/sessions/:id/ipsEvery IP a session has signed in from, with first/last seen
DELETE /api/auth/sessions/:idRevoke one session
DELETE /api/auth/sessionsRevoke all but the current one. Returns { "revoked": <count> }

User#

All endpoints require authentication.

Endpoint
Purpose
GET / PATCH /api/user/meRead or update the user (display name, avatar, profile visibility, preferences)
POST /api/user/me/change-password{ "current_password", "new_password" }
POST /api/user/me/avatarmultipart/form-data, field avatar. Max 2 MB; JPEG, PNG, WebP or GIF
POST /api/user/me/readmeSave a Markdown README
POST /api/user/me/readme/syncSync it from the user’s github.com/<login>/<login> repo
GET / POST / DELETE /api/user/me/emails[/:id]Manage secondary emails. POST /:id/resend resends; POST /:id/set-primary swaps the primary after verification
GET / PUT /api/user/me/notificationsNotification preferences. See Notifications
GET / POST / PUT / DELETE /api/user/me/notification-rulesets[/:id]Notification rulesets. See Notifications
GET / POST / DELETE /api/user/tokens[/:id]Personal access tokens. The value is shown only when created. See Personal Access Tokens
DELETE /api/user/meDelete the account: { "password": "...", "confirm": "DELETE" }

List endpoints accept ?page=, ?limit= and often ?q=, and return total.

Apps#

All endpoints require authentication. See the OAuth / OIDC Guide, the SAML Guide and Cross-App Permissions.

Method
Path
Notes
GET/api/appsApps owned by the current user
POST/api/appsCreate an app
GET/api/apps/:idRead an app
PATCH/api/apps/:idUpdate fields, including oidc_fields, optional_scopes, use_jwt_tokens, allow_self_manage_exported_permissions
POST/api/apps/:id/rotate-secretRotate the client_secret
DELETE/api/apps/:idDelete an app
GET / POST / PATCH / DELETE/api/apps/:id/scope-definitions[/:scope]Exported scopes
GET / POST / DELETE/api/apps/:id/scope-access-rules[/:ruleId]Who may add or request the app’s scopes
GET / POST / DELETE/api/apps/:id/access-rules[/:ruleId]Access whitelist
GET / PUT / DELETE/api/apps/:id/samlSAML settings, and the IdP details to give the app
GET / POST / PATCH / DELETE/api/apps/:appId/webhooks[/:id]App notifications

App secrets are write-only: the generated secret is returned only when an app is created or its secret rotated. Everywhere else you get has_client_secret instead.

Teams#

See Teams for the concepts.

Method
Path
Notes
GET/api/teamsTeams the user can reach, including inherited sub-teams (inherited_from)
POST/api/teamsCreate a team. parent_team_id makes it a sub-team. Site admins may set owner_username / owner_id
GET/api/teams/:idTeam details with my_role, ancestors, sub_teams and the first page of members
PATCH/api/teams/:idUpdate settings, join requirements, parent_team_id, groups settings
DELETE/api/teams/:idDisband the team and every sub-team
GET / POST/api/teams/:id/sub-teamsList or create sub-teams
GET/api/teams/:id/membersMembers. ?q=, ?group= (slug)
POST/api/teams/:id/membersAdd a member by username or user_id
PATCH/api/teams/:id/members/:userIdChange role
DELETE/api/teams/:id/members/:userIdRemove a member, or leave (your own id)
PATCH/api/teams/:id/membership/show-on-profileOpt in or out of the team’s public member list
GET / POST/api/teams/:id/groupsList or create member groups
PATCH / DELETE/api/teams/:id/groups/:groupIdUpdate or delete a group
PUT/api/teams/:id/members/:userId/groupsReplace a member’s groups: { "group_ids": [...] }
POST/api/teams/:id/transfer-ownershipTransfer ownership to another member
GET / POST/api/teams/:id/invitesList or create invites (email lock, max uses, one group, absolute expires_at)
PATCH / DELETE/api/teams/:id/invites/:tokenEdit, enable/disable or revoke an invite
GET/api/teams/join/:tokenPreview an invite: team, requirements, unmet items (auth optional)
POST/api/teams/join/:tokenAccept an invite
GET / POST / DELETE/api/teams/:id/domains[/:domainId]Team domains
POST/api/teams/:id/domains/:domainId/verifyRe-verify
POST/api/teams/:id/domains/:domainId/share-to-team, share-to-personal, to-personalShare a personal domain with the team, reverse it, or move it out
GET / POST/api/teams/:id/appsTeam-owned apps
POST / DELETE/api/teams/:id/apps/transfer, /api/teams/:id/apps/:appId/transferMove a personal app into the team, or back out

See Teams → Invite-link registration.

Method
Path
Notes
GET/api/join/:teamIdPublic. Team branding, requirements and captcha config
POST/api/auth/register-with-inviteCreate a pending account and sign it in
GET/api/auth/invite-join/statusWhat the pending account still has to satisfy
POST/api/auth/invite-join/completeJoin the team once the requirements are met
GET/api/user/me/restrictionWhether the caller is restricted, and whether it can convert
POST/api/user/me/convertConvert to a full account (one-way; needs a verified real email)

Domains#

Method
Path
Notes
GET/api/domainsThe user’s domains
POST/api/domainsAdd a domain. Returns the verification options (DNS TXT, HTML meta, .well-known)
POST/api/domains/:id/verifyCheck verification now
DELETE/api/domains/:idRemove

Social connections#

Method
Path
Notes
GET/api/connectionsThe user’s linked accounts
POST/api/connections/intentGet a short-lived token for linking a provider
GET/api/connections/:slug/beginStart sign-in (?mode=login) or linking (?mode=connect&intent=<token>)
GET/api/connections/:slug/callbackThe provider’s redirect target
POST/api/connections/:slug/tg-verifyVerify Telegram login data
POST/api/connections/:id/refreshRefresh display name and avatar from the provider
DELETE/api/connections/:idDisconnect

The flow must finish in the browser that started it, within 10 minutes. OAuth-token equivalents: GET /api/oauth/me/social-connections (social:read) and DELETE /api/oauth/me/social-connections/:id (social:write).

OAuth 2.0 / OIDC#

See the OAuth / OIDC Guide for the walkthrough.

Method
Path
Notes
GET/api/oauth/authorizeApp info and requested scopes for the consent screen
POST/api/oauth/authorizeApprove or deny
POST/api/oauth/parPushed Authorization Requests (RFC 9126)
POST/api/oauth/registerDynamic Client Registration (RFC 7591)
GET/PUT/DELETE/api/oauth/register/:client_idClient management (RFC 7592)
POST/api/oauth/tokenCode, refresh, device, token-exchange, SAML grants
POST/api/oauth/device_authorizationDevice Authorization Grant (RFC 8628)
GET / POST/api/oauth/userinfoOIDC UserInfo
POST/api/oauth/introspectRFC 7662
POST/api/oauth/revokeRFC 7009
GET / POST/api/oauth/end_sessionRP-Initiated Logout
GET/.well-known/openid-configurationOpenID Connect Discovery
GET/.well-known/oauth-authorization-serverRFC 8414 metadata
GET/.well-known/oauth-protected-resourceRFC 9728 metadata
GET/.well-known/webfingerIssuer discovery
GET/.well-known/jwks.jsonPublic signing keys
GET/.well-known/security.txtWhen a security contact is configured
GET/.well-known/change-passwordRedirects to the change-password page

Step-up 2FA#

Method
Path
Auth
POST/api/oauth/2fa/challengesApp credentials (HTTP Basic) or PKCE
POST/api/oauth/2fa/verifyApp credentials — exchange the redirect code for the result
POST/api/oauth/2fa/sudo/revokeUser session — end a sudo window

The other step-up endpoints serve Prism’s own confirmation page.

/api/oauth/me/* (token-authenticated)#

These accept an OAuth access token or a personal access token. Scopes are listed in OAuth → Scopes.

Path
Scope
GET /me/profileprofile
PATCH /me/profileprofile:write
GET / POST / PATCH / DELETE /me/apps[/:id]apps:read / apps:write
GET /me/team-appsapps:read
GET / POST / PATCH / DELETE /me/teams[/:id]teams:read / teams:create / teams:write / teams:delete
POST / DELETE /me/teams/:id/membersteams:write
GET / POST / DELETE /me/domains, POST /me/domains/:domain/verifydomains:read / domains:write
GET / POST / DELETE /me/gpg-keysgpg:read / gpg:write
GET / DELETE /me/social-connectionssocial:read / social:write
GET / PATCH / DELETE /me/admin/usersadmin:users:read / :write / :delete
GET / PATCH /me/admin/configadmin:config:read / admin:config:write
GET / POST / DELETE /me/invitesadmin:invites:read / :create / :delete
GET /me/team/:teamId/info, PATCHteam:<id>:read / team:<id>:write
GET / POST / PATCH / DELETE /me/team/:teamId/members[...]team:<id>:member:read / team:<id>:member:write
GET /me/team/:teamId/members/:userId/profileteam:<id>:member:profile:read

The /me/team/:teamId/... paths need a token bound to that team (see OAuth → Team scopes); a teams:* token isn’t enough.

POST /me/domains takes { "domain": "example.com" } and returns 201 with the domain’s id, domain, verification_token, verified, and the values for each verification method: txt_record / txt_value (DNS TXT), http_url / http_path / http_value (.well-known file) and meta_tag (HTML meta). If the user already has a verified parent domain (for example example.com when adding app.example.com), the new domain is verified on the spot: verified is true and verified_by_parent names that parent.

GET /api/oauth/consents / DELETE /api/oauth/consents/:client_id#

List the apps the current user has authorized, or revoke one. Revoking removes the consent and all outstanding tokens for the app.

SAML#

See the SAML Guide.

Method
Path
Notes
GET/saml/metadataIdentity provider metadata
GET / POST/saml/ssoSingle sign-on, HTTP-Redirect or HTTP-POST binding
GET / POST/saml/sloSingle logout, HTTP-Redirect or HTTP-POST binding
GET / POST / PATCH / DELETE/api/saml/profiles[/:id]The current user’s SAML profiles. Create and rename take { "name" }
POST/api/saml/profiles/:id/shareTurn a profile made for one app into a shared one: { "name" }

A profile made for one app can’t be renamed or deleted, and a shared profile can’t be deleted while an app uses it. The other /api/saml/* endpoints serve Prism’s own sign-in and sign-out pages.

GET /api/search?q=<text>#

Powers the command palette (Ctrl/⌘ K). Requires a session. Matches names containing q (at least 2 characters) and returns up to 5 results per kind:

json
{
  "results": [
    {
      "kind": "app",
      "admin": false,
      "id": "…",
      "title": "My app",
      "subtitle": "prism_…",
      "url": "/apps/…"
    }
  ]
}

kind is app, team, domain, token, consent, user or oauth_source. Admins also get site-wide results (admin: true).

Public profiles#

GET /api/users/:username#

The user’s profile, filtered by what they chose to share. Returns 404 if the user doesn’t exist, is private, or profiles are switched off; the response is the same in all three cases. See Public Profiles.

GET /api/public/teams/:id#

The team’s profile, with the same 404 rules. Includes sub_teams (only those that are public themselves) and a parent_team breadcrumb when the parent is public.

Avatar proxy#

Remote avatar and icon images are served through Prism so pages don’t load third-party images directly.

  • POST /api/proxy/image/register (authenticated) registers a remote HTTPS image URL and returns { "id": "...", "url": "/api/proxy/image/<id>" }. Private and reserved addresses are rejected.

  • GET /api/proxy/image/:id serves the image. It’s safe to embed: SVGs are rebuilt from an allowlist of drawing elements, and an SVG that isn’t well-formed XML is refused. Images over 5 MiB are refused too. Only registered IDs work; it isn’t an open proxy.

Admin#

All admin endpoints need a user with the admin role. The dashboard uses a matching /api/admin/* endpoint for every admin action; the main ones are:

Path
Purpose
GET / PATCH /api/admin/configRead or update settings. Secrets are redacted and encrypted on write
GET /api/admin/statsTotals
GET /api/admin/users, GET / PATCH / DELETE /api/admin/users/:idList, read, update (role, active, email, per-user token lifetimes) or delete users
DELETE /api/admin/users/:id/sessionsRevoke all of a user’s sessions
POST /api/admin/users/bulk{ user_ids, action } — activate, deactivate or delete; up to 50
GET / PATCH /api/admin/apps[/:id]Verify or deactivate apps
POST /api/admin/apps/:id/transfer{ owner_id } or { team_id }
GET / POST / PATCH / DELETE /api/admin/oauth-sources[/:id]Manage OAuth sources
GET /api/admin/oauth-sources/discoverFetch OIDC discovery for an issuer
GET / POST / DELETE /api/admin/invites[/:id]Site invites
GET /api/admin/teams, DELETE /api/admin/teams/:idList or disband teams
GET /api/admin/domains, POST /api/admin/domains/:id/verify, DELETE /api/admin/domains/:idDomains, including force-verify
GET /api/admin/audit-logPlatform audit log
GET /api/audit/:scope/exportExport an audit log you can read: ?format=csv|json, up to 10,000 events
GET /api/admin/login-errorsFailed sign-ins
POST /api/admin/test-emailSend a test email
GET /api/notices, POST /api/notices/:id/dismissNotices for the current viewer (public notices work signed out)

The Database console, key–value browser, secrets migrations, notices editor, scope grants and other maintenance tools are driven by the admin panel; see the Admin Guide.

Health#

GET /api/health#

Returns { "ok": true }. No authentication.