openapi: 3.2.0
info:
  title: Goalkeeper Authentication API
  version: 0.0.0
  description: Public REST API.
servers:
- url: http://localhost:3001
  description: Local development
tags:
- name: Authentication
  description: User session lifecycle.
paths:
  /v1/auth/session:
    get:
      operationId: getAuthSession
      summary: Get the current session
      description: Returns the authenticated user for the current session.
      tags:
      - Authentication
      responses:
        '200':
          description: The current authenticated session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSession'
        '401':
          description: The request is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/config:
    get:
      operationId: getAuthConfiguration
      summary: Get authentication configuration
      description: Returns the authentication method configured for this service.
      tags:
      - Authentication
      responses:
        '200':
          description: Authentication configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthConfiguration'
  /v1/auth/login:
    get:
      operationId: beginAuthLogin
      summary: Begin login
      description: Starts the configured login flow and redirects the browser.
      tags:
      - Authentication
      parameters:
      - name: returnTo
        in: query
        required: false
        description: Same-origin application URL to open after login.
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Continue the login flow.
          headers:
            Location:
              description: The next browser location.
              schema:
                type: string
                format: uri
    post:
      operationId: loginWithEmail
      summary: Sign in with email
      description: Authenticates a verified email principal and starts a session.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailLoginRequest'
      responses:
        '200':
          description: The session started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTransitionResponse'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The request is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The request origin is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/register:
    post:
      operationId: registerWithEmail
      summary: Register with email
      description: Creates an email principal and sends a verification link.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRegistrationRequest'
      responses:
        '202':
          description: Email verification is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRegistrationResponse'
        '400':
          description: The registration request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The request origin is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/verify-email:
    post:
      operationId: verifyEmail
      summary: Verify an email principal
      description: Consumes a single-use verification token after explicit browser confirmation.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailVerificationRequest'
      responses:
        '200':
          description: The email principal was verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTransitionResponse'
        '400':
          description: The verification token is invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The request origin is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/callback:
    get:
      operationId: completeAuthLogin
      summary: Complete login
      description: Completes the configured login flow and redirects the browser.
      tags:
      - Authentication
      parameters:
      - name: returnTo
        in: query
        required: false
        description: Same-origin application URL to open after login.
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Open the authenticated application page.
          headers:
            Location:
              description: The authenticated application location.
              schema:
                type: string
                format: uri
  /v1/auth/logout:
    post:
      operationId: logoutAuthSession
      summary: Log out
      description: Ends the current session and returns the next browser location.
      tags:
      - Authentication
      responses:
        '200':
          description: The session ended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTransitionResponse'
        '403':
          description: The request origin is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    EmailLoginRequest:
      type: object
      additionalProperties: false
      required:
      - email
      - password
      - returnTo
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        password:
          type: string
          minLength: 12
          maxLength: 512
        returnTo:
          type: string
          format: uri
    AuthUser:
      type: object
      additionalProperties: false
      required:
      - id
      - displayName
      - email
      properties:
        id:
          type: string
        displayName:
          type: string
        email:
          type: string
          format: email
    EmailRegistrationResponse:
      type: object
      additionalProperties: false
      required:
      - emailVerificationRequired
      - email
      properties:
        emailVerificationRequired:
          type: boolean
          const: true
        email:
          type: string
          format: email
    AuthConfiguration:
      type: object
      additionalProperties: false
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - redirect
          - email
    OrganizationRole:
      type: string
      enum:
      - owner
      - admin
      - member
    EmailVerificationRequest:
      type: object
      additionalProperties: false
      required:
      - token
      properties:
        token:
          type: string
          minLength: 1
    AuthSession:
      type: object
      additionalProperties: false
      required:
      - user
      - activeOrganizationId
      - organizations
      properties:
        user:
          $ref: '#/components/schemas/AuthUser'
        activeOrganizationId:
          type: string
          format: uuid
        organizations:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrganizationSummary'
    EmailRegistrationRequest:
      type: object
      additionalProperties: false
      required:
      - email
      - password
      - displayName
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        password:
          type: string
          minLength: 12
          maxLength: 512
        displayName:
          type: string
          minLength: 1
          maxLength: 100
    OrganizationSummary:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - role
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
          maxLength: 100
        role:
          $ref: '#/components/schemas/OrganizationRole'
    AuthTransitionResponse:
      type: object
      additionalProperties: false
      required:
      - redirectTo
      properties:
        redirectTo:
          type: string
          format: uri
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Goalkeeper API token or provider-issued OAuth access token.
    cookieAuth:
      type: apiKey
      in: cookie
      name: goalkeeper_session