generated: '2026-08-13'
method: searched
source: https://help.icontact.com/customers/s/article/API-Getting-Started-Guide
docs: https://help.icontact.com/customers/s/article/API-Getting-Started-Guide
name: iContact REST API authentication
api: icontact:rest-api
base_url: https://app.icontact.com/icp
summary: >-
  iContact authenticates every request with three custom HTTP request headers
  issued per registered application, not with OAuth, Basic auth or a bearer
  token. There is no authorization server, no token exchange, no scopes and no
  refresh; the same three long-lived header values are sent on every call. A
  fourth header, API-Version, selects the API contract version and is also
  required.
transport:
  https_required: true
  https_note: >-
    The Getting Started guide states "Every request must be sent over HTTPS."
    Probed 2026-08-13: https://app.icontact.com/icp/time returns
    strict-transport-security: max-age=15552000; includeSubDomains.
schemes:
  - id: api-app-headers
    type: apiKey
    in: header
    style: custom-multi-header
    headers:
      - name: API-AppId
        required: true
        description: >-
          Uniquely identifies the registered API application. Issued when the
          integration is created under Settings and Billing > iContact
          Integrations > Custom API Integrations. A third-party application
          distributes its own API-AppId, which the account owner must enable at
          https://app.icontact.com/icp/core/externallogin before use.
      - name: API-Username
        required: true
        description: The iContact account username used to log in to iContact.
      - name: API-Password
        required: true
        description: >-
          The API application password set when the application was registered.
          The docs state explicitly that this is NOT the iContact login
          password, and recommend it differ from the account password.
      - name: API-Version
        required: true
        description: >-
          Selects the API contract version. Documented accepted values are
          2.0, 2.1 and 2.2. The first-party PHP libraries default to 2.2.
        values: ['2.0', '2.1', '2.2']
    rotation: >-
      Not documented. The docs describe setting the application password at
      registration time and say nothing about rotation, expiry or revocation.
    scopes: null
    scopes_note: >-
      No scope or permission scoping exists on the credential itself.
      Authorization is account-level; see the permissions resource
      (https://help.icontact.com/customers/s/article/Permissions-iContact-API),
      which grants a USER read/write access per client folder — it does not
      constrain an API application.
content_negotiation:
  headers: [Accept, Content-Type]
  values: [application/json, text/xml]
  note: >-
    The API returns 406 Not Acceptable for any other requested representation
    and 415 Unsupported Media Type for any other request body format.
unauthenticated_surface:
  - path: /icp/time
    method: GET
    description: >-
      The time resource is documented as publicly accessible and is the only
      documented exception to "every request must be authenticated".
    probed: '2026-08-13'
    url: https://app.icontact.com/icp/time
    http_status: 200
    response: '{"time":"2026-08-13T13:30:19-04:00","timestamp":1786642219}'
failure_behavior:
  status: 401
  body: '{"errors":["Api username invalid"]}'
  probed: '2026-08-13'
  probed_url: https://app.icontact.com/icp/a/
  note: >-
    Probed anonymously and with placeholder credentials; both return HTTP 401
    with the same custom error envelope. No WWW-Authenticate header is sent.
account_scoping:
  required_path_ids: [accountId, clientFolderId]
  note: >-
    Almost every resource URI is namespaced /a/{accountId}/c/{clientFolderId}/…
    Both identifiers are read from the iContact UI (Settings and Billing >
    iContact Integrations > View Details > Account Information), or discovered
    at runtime by calling GET /a/ then GET /a/{accountId}/c/.
not_supported:
  oauth2: false
  openid_connect: false
  mutual_tls: false
  bearer_token: false
  hmac_request_signing: false
gaps:
  - No OAuth 2.0 or OpenID Connect, so no delegated third-party authorization.
  - No scopes; a credential that can read contacts can also delete them.
  - No documented credential rotation, expiry or revocation procedure.
  - Credentials travel as three separate custom headers on every request.