openapi: 3.1.0
info:
  title: Coherta API
  version: "2026-04-24"
  description: |
    This OpenAPI file documents the shared authentication rules and the core auth
    endpoints. The landing page lives in /docs, and the searchable endpoint
    reference lives in /docs/reference.php.

servers:
  - url: /
    description: Same host as the application

tags:
  - name: Authentication
    description: Login and token refresh flows
  - name: Conventions
    description: Shared routing and authorization conventions

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TokenRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: CRM username
        password:
          type: string
          description: CRM password
    TokenResponse:
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          description: JWT access token used in the Authorization header
        token_type:
          type: string
          example: bearer
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message

paths:
  /token:
    post:
      tags:
        - Authentication
      summary: Issue a bearer token
      description: |
        Exchanges a username and password for a JWT in the access_token field.
        Clients should then send the token as:
        Authorization: Bearer <access_token>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenRequest"
      responses:
        "200":
          description: Token issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /token/renew:
    post:
      tags:
        - Authentication
      summary: Refresh a bearer token
      description: |
        Requires a valid Authorization header in this format:
        Authorization: Bearer <access_token>
        Returns a new JWT in access_token.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Token refreshed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /docs:
    get:
      tags:
        - Conventions
      summary: Open developer landing page
      description: |
        The landing page introduces authentication, quickstart guidance, and
        links into the full API reference.
      responses:
        "200":
          description: HTML developer landing page

  /docs/reference.php:
    get:
      tags:
        - Conventions
      summary: Open searchable API reference
      description: |
        The full endpoint reference lives here, with endpoint search, filters,
        and detailed route cards.
      responses:
        "200":
          description: HTML API reference

x-docs:
  portal: /docs/
  reference: /docs/reference.php
  notes:
    - Use /token to obtain a JWT access token for protected endpoints.
    - Use /token/renew to refresh an existing bearer token.
    - Some endpoints support path-style IDs in addition to query parameters.
