openapi: 3.0.3
info:
  title: Armor FH-AUTH Security API
  description: |
    Armor Security Platform Authentication API using FH-AUTH flow.
  version: 2.0.0
  contact:
    name: Armor Support
    url: https://armor.com

servers:
  - url: https://api.armor.com
    description: Production API

paths:
  /auth/authorize:
    post:
      operationId: authorize
      summary: Get authorization code
      description: |
        Authenticates user credentials and returns an authorization code.
        The code must be exchanged for an access token within 2 minutes.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
      responses:
        '200':
          description: Authorization code issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many authentication attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/token:
    post:
      operationId: exchangeToken
      summary: Exchange authorization code for access token
      description: |
        Exchanges an authorization code for an access token and ID token.
        The authorization code must be used within 2 minutes of issuance.
        Access tokens are valid for 15 minutes.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Tokens issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid or expired authorization code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/token/reissue:
    post:
      operationId: refreshToken
      summary: Refresh an access token
      description: |
        Exchanges an existing access token for a new one.
        Use this endpoint when the current token is about to expire or has expired.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
      responses:
        '200':
          description: New token issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /me:
    get:
      operationId: getCurrentUser
      summary: Get current user information
      description: Returns the authenticated user's profile and associated accounts
      tags:
        - User
      security:
        - FH-AUTH: []
      parameters:
        - $ref: '#/components/parameters/X-Account-Context'
      responses:
        '200':
          description: Current user information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          description: Unauthorized - invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - invalid account context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    FH-AUTH:
      type: http
      scheme: bearer
      bearerFormat: FH-AUTH
      description: |
        FH-AUTH token authentication.

        ## Authentication Flow

        1. **Authorize**: POST credentials to `/auth/authorize` to receive an authorization code
        2. **Token Exchange**: Exchange the code at `/auth/token` within 2 minutes for access tokens
        3. **API Calls**: Use the access token in the `Authorization: FH-AUTH {token}` header
        4. **Refresh**: When token expires (15 minutes), refresh via `/auth/token/reissue`

        ## Security Notes

        - Authorization codes expire in 2 minutes
        - Access tokens expire in 15 minutes
        - All endpoints require HTTPS
        - Never log or persist tokens in plain text

        Include the access token in the Authorization header:
        ```
        Authorization: FH-AUTH {access_token}
        ```

  parameters:
    X-Account-Context:
      name: X-Account-Context
      in: header
      required: true
      description: The account ID context for the request
      schema:
        type: string
        example: "1000"

  schemas:
    AuthorizeRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          format: email
          description: User's email address
          example: "user@example.com"
        password:
          type: string
          format: password
          description: User's password
          writeOnly: true

    AuthorizeResponse:
      type: object
      properties:
        code:
          type: string
          description: Authorization code valid for 2 minutes
          example: "abc123xyz..."
        expiresIn:
          type: integer
          description: Seconds until code expires
          example: 120

    TokenRequest:
      type: object
      required:
        - code
        - grant_type
      properties:
        code:
          type: string
          description: Authorization code from /auth/authorize
          example: "abc123xyz..."
        grant_type:
          type: string
          enum:
            - authorization_code
          description: Must be "authorization_code"
          example: "authorization_code"

    RefreshRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: Current access token to refresh
          example: "eyJhbGciOiJSUzI1NiIs..."

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Access token for API calls (valid for 15 minutes)
          example: "eyJhbGciOiJSUzI1NiIs..."
        id_token:
          type: string
          description: ID token containing user identity claims
          example: "eyJhbGciOiJSUzI1NiIs..."
        token_type:
          type: string
          description: Token type (always "FH-AUTH")
          example: "FH-AUTH"
        expires_in:
          type: integer
          description: Seconds until access token expires
          example: 900

    MeResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'

    User:
      type: object
      properties:
        type:
          type: string
          example: "user"
        username:
          type: string
          format: email
          example: "john.doe@armor.com"
        firstName:
          type: string
          example: "John"
        lastName:
          type: string
          example: "Doe"
        links:
          $ref: '#/components/schemas/UserLinks'
        passwordExpiry:
          type: string
          description: Password expiry time in seconds
          example: "2609961"

    UserLinks:
      type: object
      properties:
        userId:
          type: integer
          example: 4922

    Account:
      type: object
      properties:
        id:
          type: integer
          example: 1000
        currency:
          type: string
          example: "USD"
        name:
          type: string
          example: "Armor Internal Test_AA"
        status:
          type: string
          enum:
            - Claimed
            - Pending
            - Inactive
          example: "Claimed"
        parent:
          type: integer
          nullable: true
          example: 1
        products:
          type: array
          nullable: true
          items:
            type: string
        accountType:
          type: string
          enum:
            - Partner
            - Direct
            - Partner Customer
          example: "Partner"
        isSynced:
          type: boolean
          example: true
        isFreeTrial:
          type: boolean
          example: false

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: "invalid_credentials"
        error_description:
          type: string
          description: Human-readable error message
          example: "The provided credentials are invalid"
        status:
          type: integer
          description: HTTP status code
          example: 401

tags:
  - name: Authentication
    description: |
      FH-AUTH authentication flow endpoints.

      ## Flow Overview
      1. POST `/auth/authorize` with credentials → receive authorization code
      2. POST `/auth/token` with code → receive access token
      3. Use `Authorization: FH-AUTH {token}` header for API calls
      4. POST `/auth/token/reissue` to refresh expired tokens
  - name: User
    description: User profile and account information
