headroom/backend/.scribe/endpoints/00.yaml

name: Authentication
description: |-

  Endpoints for JWT authentication and session lifecycle.
endpoints:
  -
    custom: []
    httpMethods:
      - POST
    uri: api/auth/login
    metadata:
      custom: []
      groupName: Authentication
      groupDescription: |-

        Endpoints for JWT authentication and session lifecycle.
      subgroup: ''
      subgroupDescription: ''
      title: 'Login and get tokens'
      description: 'Authenticate with email and password to receive an access token and refresh token.'
      authenticated: false
      deprecated: false
    headers:
      Content-Type: application/json
      Accept: application/json
    urlParameters: []
    cleanUrlParameters: []
    queryParameters: []
    cleanQueryParameters: []
    bodyParameters:
      email:
        custom: []
        name: email
        description: 'User email address.'
        required: true
        example: user@example.com
        type: string
        enumValues: []
        exampleWasSpecified: true
        nullable: false
        deprecated: false
      password:
        custom: []
        name: password
        description: 'User password.'
        required: true
        example: secret123
        type: string
        enumValues: []
        exampleWasSpecified: true
        nullable: false
        deprecated: false
    cleanBodyParameters:
      email: user@example.com
      password: secret123
    fileParameters: []
    responses:
      -
        custom: []
        status: 200
        content: |-
          {
            "data": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Alice Johnson",
              "email": "user@example.com",
              "role": "manager",
              "active": true,
              "created_at": "2026-01-01T00:00:00Z",
              "updated_at": "2026-01-01T00:00:00Z"
            },
            "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
            "refresh_token": "abc123def456",
            "token_type": "bearer",
            "expires_in": 3600
          }
        headers: []
        description: ''
      -
        custom: []
        status: 401
        content: '{"message":"Invalid credentials"}'
        headers: []
        description: ''
      -
        custom: []
        status: 403
        content: '{"message":"Account is inactive"}'
        headers: []
        description: ''
      -
        custom: []
        status: 422
        content: '{"errors":{"email":["The email field is required."],"password":["The password field is required."]}}'
        headers: []
        description: ''
    responseFields: []
    auth: []
    controller: null
    method: null
    route: null
  -
    custom: []
    httpMethods:
      - POST
    uri: api/auth/refresh
    metadata:
      custom: []
      groupName: Authentication
      groupDescription: |-

        Endpoints for JWT authentication and session lifecycle.
      subgroup: ''
      subgroupDescription: ''
      title: 'Refresh access token'
      description: 'Exchange a valid refresh token for a new access token and refresh token pair.'
      authenticated: true
      deprecated: false
    headers:
      Content-Type: application/json
      Accept: application/json
    urlParameters: []
    cleanUrlParameters: []
    queryParameters: []
    cleanQueryParameters: []
    bodyParameters:
      refresh_token:
        custom: []
        name: refresh_token
        description: 'Refresh token returned by login.'
        required: true
        example: abc123def456
        type: string
        enumValues: []
        exampleWasSpecified: true
        nullable: false
        deprecated: false
    cleanBodyParameters:
      refresh_token: abc123def456
    fileParameters: []
    responses:
      -
        custom: []
        status: 200
        content: |-
          {
            "data": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Alice Johnson",
              "email": "user@example.com",
              "role": "manager",
              "active": true,
              "created_at": "2026-01-01T00:00:00Z",
              "updated_at": "2026-01-01T00:00:00Z"
            },
            "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
            "refresh_token": "newtoken123",
            "token_type": "bearer",
            "expires_in": 3600
          }
        headers: []
        description: ''
      -
        custom: []
        status: 401
        content: '{"message":"Invalid or expired refresh token"}'
        headers: []
        description: ''
    responseFields: []
    auth: []
    controller: null
    method: null
    route: null
  -
    custom: []
    httpMethods:
      - POST
    uri: api/auth/logout
    metadata:
      custom: []
      groupName: Authentication
      groupDescription: |-

        Endpoints for JWT authentication and session lifecycle.
      subgroup: ''
      subgroupDescription: ''
      title: 'Logout current session'
      description: 'Invalidate a refresh token and end the active authenticated session.'
      authenticated: true
      deprecated: false
    headers:
      Content-Type: application/json
      Accept: application/json
    urlParameters: []
    cleanUrlParameters: []
    queryParameters: []
    cleanQueryParameters: []
    bodyParameters:
      refresh_token:
        custom: []
        name: refresh_token
        description: 'Optional refresh token to invalidate immediately.'
        required: false
        example: abc123def456
        type: string
        enumValues: []
        exampleWasSpecified: true
        nullable: false
        deprecated: false
    cleanBodyParameters:
      refresh_token: abc123def456
    fileParameters: []
    responses:
      -
        custom: []
        status: 200
        content: '{"message":"Logged out successfully"}'
        headers: []
        description: ''
    responseFields: []
    auth: []
    controller: null
    method: null
    route: null