> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collectwise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify API Security

> Check signing and the observed source IP before enabling enforcement. A valid key is always required. If any usable current/grace signing secret exists, its valid signature is required even when enforcement is off. With signing off and no secret, signature is skipped; required signing with no secret returns 401. Failed signature never reveals IP details. No provider calls, business/settings writes or last-used updates. An authenticated IP mismatch can return 200, so inspect ipAllowlistEnabled and ipMatch.



## OpenAPI

````yaml POST /security/verify
openapi: 3.0.1
info:
  title: CollectWise API
  description: >-
    An API for managing debtors, tracking statuses, and automating debt
    collection processes
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://collectwiseapi.com
security:
  - apiKey: []
paths:
  /security/verify:
    post:
      summary: Verify API security
      description: >-
        Check signing and the observed source IP before enabling enforcement. A
        valid key is always required. If any usable current/grace signing secret
        exists, its valid signature is required even when enforcement is off.
        With signing off and no secret, signature is skipped; required signing
        with no secret returns 401. Failed signature never reveals IP details.
        No provider calls, business/settings writes or last-used updates. An
        authenticated IP mismatch can return 200, so inspect ipAllowlistEnabled
        and ipMatch.
      operationId: verifyApiSecurity
      parameters:
        - $ref: '#/components/parameters/CwTimestamp'
        - $ref: '#/components/parameters/CwSignature'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: >-
                Optional JSON object. Contents are not used; sign the exact
                bytes sent.
            example: {}
      responses:
        '200':
          description: >-
            Authenticated diagnostics. An IP mismatch is reported here instead
            of denied; normal business routes still enforce it. No
            business/settings/last-used writes.
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - signature
                  - signingRequired
                  - sourceIp
                  - ipAllowlistEnabled
                  - ipMatch
                properties:
                  signature:
                    type: string
                    enum:
                      - verified
                      - skipped
                  signingRequired:
                    type: boolean
                  sourceIp:
                    type: string
                    description: >-
                      Trusted caller IP from API Gateway. Documentation examples
                      use TEST-NET addresses.
                  ipAllowlistEnabled:
                    type: boolean
                  ipMatch:
                    type: boolean
                    description: >-
                      Whether the caller matches a saved range, independent of
                      enforcement. False when there are no saved ranges.
              example:
                signature: verified
                signingRequired: false
                sourceIp: 203.0.113.10
                ipAllowlistEnabled: false
                ipMatch: false
        '400':
          description: Malformed JSON body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized key or signature; generic error without IP details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '413':
          description: Body exceeds 100 KiB.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '415':
          description: Unsupported body content type, compression or charset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '503':
          description: Security dependency or trusted request metadata unavailable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  parameters:
    CwTimestamp:
      name: x-cw-timestamp
      in: header
      required: false
      description: >-
        Required together with x-cw-signature when signing is enabled for this
        key or organization. POST /security/verify also requires signing
        whenever a usable secret exists. Canonical Unix seconds, within ±300
        seconds. See API Access for CW1 signing.
      schema:
        type: string
        pattern: ^(0|[1-9][0-9]*)$
    CwSignature:
      name: x-cw-signature
      in: header
      required: false
      description: >-
        CW1 HMAC-SHA256 signature: v1= followed by 64 lowercase hex digits. Use
        the decoded 32-byte signing secret and exact request bytes. See API
        Access.
      schema:
        type: string
        pattern: ^v1=[0-9a-f]{64}$
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: collectwise_key
      description: >-
        Active, unexpired API key belonging to an active organization. Optional
        organization/key signing and organization IP restrictions also apply;
        see API Access.

````