Authentication

Overview

Integrations authenticate to the Pool Office Manager API with an API key. A key is a long-lived secret that you create in the web app and present on every request in the Authorization header. Each key carries its own fixed set of scopes, so a key can only read or modify the resources you explicitly grant it.

Creating an API Key

API keys are created from the web app by an organization administrator:

1. Navigate to Settings → API Keys.
2. Click Create API Key, give it a descriptive name, and select the scopes the key should be allowed to use.
3. Optionally set an expiry date. If you leave it blank, the key remains valid until it is revoked.
4. Click Create. The full key is displayed exactly once.

Every key begins with the recognizable, non-secret prefix pom_live_ followed by a high-entropy secret:

pom_live_3f9c1a7b8d2e4f60a1c5e8b9d0f2a4c6e7b1d3f5a8c0e2b4d6f8a1c3e5b7d9f

Treat the key like a password. Store it in your integration's secret manager — never commit it to source control or expose it in a browser.

Using the Key

Send the key as a bearer token in the Authorization header on every request to the GraphQL endpoint:

Authorization: Bearer pom_live_<your_api_key>

A minimal request that confirms the key works — it returns the organization the key belongs to:

query {
  authenticatedUser {
    id
    email
    organization {
      id
      name
    }
  }
}

{
  "data": {
    "authenticatedUser": {
      "id": "usr_8a1c3e5b7d9f",
      "email": "service-account@example.com",
      "organization": {
        "id": "org_2b4d6f8a1c3e",
        "name": "Blue Wave Pools"
      }
    }
  }
}

Scopes

A key can only access the resources its scopes allow. Scopes are chosen when the key is created and follow a action:resource shape. Grant the narrowest set your integration needs.

You can only grant a key scopes that you yourself hold. The update:organization scope — which governs API-key management itself — is reserved for interactive administrator sessions and cannot be exercised by an API key, so a key can never create, edit, or revoke other keys.

Example: Make.com Integration

Suppose you want a Make.com scenario that creates a customer in Pool Office Manager whenever a new lead arrives. Create a key scoped to write:customer (add read:customer if the scenario needs to look records up first), then point Make.com's HTTP module at the GraphQL endpoint with the key in the Authorization header.

mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    id
    firstName
    lastName
    email
  }
}

{
  "data": {
    "createCustomer": {
      "id": "cus_5b7d9f1a3c5e",
      "firstName": "Jordan",
      "lastName": "Rivera",
      "email": "jordan.rivera@example.com"
    }
  }
}

In Make.com, store the key in the connection's Authorization header (or as a custom header in the HTTP module) so it is not exposed in the scenario blueprint.

Expiry & Revocation

• Expiry. If a key was given an expiry date, it stops authenticating the moment that date passes. Keys created without an expiry date remain valid until revoked.
• Revocation. An administrator can revoke a key at any time from Settings → API Keys. Revocation takes effect almost immediately — in-flight cached sessions are invalidated, so a revoked key cannot be resurrected.
• Rotation. To rotate a key, create a new one, deploy it to your integration, and then revoke the old one. Because each key is independent, rotation never disrupts your other integrations.

A revoked or expired key is treated exactly like an invalid one: the request is rejected with 401 Unauthorized.

Error Responses

Authentication and authorization failures return these status codes: