generated: '2026-08-13'
method: probed
source: >-
  https://api.pavoot.com/openapi.json (no securitySchemes declared) +
  https://api.pavoot.com/me (401 probe) +
  https://clerk.pavoot.com/.well-known/openid-configuration
name: Pavoot Application API authentication
summary: >-
  Pavoot's application API at api.pavoot.com is authenticated with Clerk-issued
  session tokens presented as a bearer credential. The published OpenAPI declares
  NO components.securitySchemes and NO operation-level security, so the auth model
  below was established by probing the live API and Pavoot's own Clerk OIDC
  discovery document — not read from the spec.
schemes:
- id: clerk_session_bearer
  type: http
  scheme: bearer
  bearer_format: JWT
  in: header
  header: Authorization
  description: >-
    Clerk-issued session JWT. Verified against the Pavoot Clerk instance
    (issuer https://clerk.pavoot.com, RS256, JWKS at
    https://clerk.pavoot.com/.well-known/jwks.json). The GET /me operation
    documents that "Clerk is shared across multiple Pavoot apps, so a valid
    Clerk session does NOT imply the user belongs here" — app membership is
    resolved from this application's own database, not from Clerk
    public_metadata.
  declared_in_spec: false
  evidence:
    url: https://api.pavoot.com/me
    http_status: 401
    body: '{"detail":"Unauthorized: Authentication failed"}'
- id: clerk_oauth2
  type: oauth2
  flow: authorization_code
  pkce: S256
  issuer: https://clerk.pavoot.com
  authorization_endpoint: https://clerk.pavoot.com/oauth/authorize
  token_endpoint: https://clerk.pavoot.com/oauth/token
  introspection_endpoint: https://clerk.pavoot.com/oauth/token_info
  revocation_endpoint: https://clerk.pavoot.com/oauth/token/revoke
  userinfo_endpoint: https://clerk.pavoot.com/oauth/userinfo
  jwks_uri: https://clerk.pavoot.com/.well-known/jwks.json
  grant_types:
  - authorization_code
  - refresh_token
  token_endpoint_auth_methods:
  - client_secret_basic
  - client_secret_post
  - none
  description: >-
    Pavoot runs a Clerk-hosted OAuth 2.0 / OpenID Connect authorization server on
    its own subdomain. Discovery is anonymous and returns a real RFC 8414 / OIDC
    document. This is the identity layer behind the app; Pavoot does not publish a
    developer OAuth client-registration flow.
  evidence:
    url: https://clerk.pavoot.com/.well-known/openid-configuration
    http_status: 200
    content_type: application/json
unauthenticated_surfaces:
- path: /openapi.json
  note: The FastAPI-generated OpenAPI document is served publicly with no auth.
  http_status: 200
- path: /docs
  note: FastAPI Swagger UI, publicly reachable.
  http_status: 200
- path: /redoc
  note: FastAPI ReDoc, publicly reachable.
  http_status: 200
- path: /attendee-registration-info/{token}
  note: >-
    Explicitly public per its own description ("Public: returns project name and
    layout for the registration form. No auth required.") — token-scoped, not
    session-scoped.
- path: /register-attendee
  note: >-
    Accepts a public registration token for attendee self-registration; the
    member-token variant requires a signed-in Clerk user.
- path: /upload-link-by-token
  note: Upload-link token surface, resolved by opaque token rather than session.
authorization:
  model: >-
    Fine-grained, database-backed RBAC layered on top of the Clerk session. The API
    exposes an explicit permission surface rather than OAuth scopes: role and user
    permission matrices, permission presets with a settable default, per-task
    permissions, and a middleware helper.
  surfaces:
  - operationId: check_route_access_endpoint_checkRouteAccess_get
    path: /checkRouteAccess
    note: >-
      Returns {"allowed": true|false} for the current user and a given path; used
      by the frontend middleware to gate /faces, /personalized-tags,
      /photographers, /recipients.
  - operationId: get_effective_permissions_endpoint_getEffectivePermissions_get
    path: /getEffectivePermissions
  - operationId: get_effective_org_permissions_endpoint_getEffectiveOrgPermissions_get
    path: /getEffectiveOrgPermissions
  - path: /org/permissions/role-matrix
  - path: /org/permissions/user-matrix
  - path: /org/permission-presets
  - path: /admin/isAdmin
  tenancy: >-
    Two-level tenancy — organization (organizationId) and project (projectId).
    Nearly every read operation is scoped by a required projectId or
    organizationId query parameter; admin/* operations are gated on a separate
    platform-admin check.
developer_access:
  public_signup: false
  api_keys: false
  note: >-
    Pavoot publishes no developer program, no API key issuance, and no partner
    OAuth client registration. Credentials are obtained by being a user of the
    Pavoot application, not by registering as an API consumer. The OpenAPI is
    readable by anyone; the API itself is not callable by anyone.