Get started

1. Choose your integration

System keys, counter keys, and counter license keys are separate credentials. The steps below create a system API key for customer-account integrations.

2. Create your first system API key

1. Sign in to BottleSpeed as an active Owner or PrimaryOwner of the target system.
2. Open /application/{systemSlug}/profile and select the Developer tab. The slug is the system name in your application URL, for example north-buffalo.
3. Choose Permissions: Read for retrieval or Read-Write if the integration creates or changes records.
4. Choose Expiration: Never, 7 days, 30 days, or 90 days.
5. Select Generate API key, then Copy API key. The complete secret appears only once. Save it before leaving the result.
6. Store it in the integration server’s secret storage. Keep it outside browser bundles, source control, and request logs.

API-key permissions do not grant a system role. Customer-account management still requires the creator’s current active Owner/PrimaryOwner membership. An account-specific Owner role is different. Keys also authorize other system APIs allowed for their creator; they have no account-only scope.

3. Make your first request

Set SYSTEM_SLUG and API_KEY in your server environment, then request one account page. The base URL is https://bottlespeed.com.

curl --fail-with-body \
  "https://bottlespeed.com/api/system/$SYSTEM_SLUG/customer-account?page=1&pageSize=25" \
  -H "x-api-key: $API_KEY"

An empty system returns:

{
  "customerAccounts": [],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 0,
    "totalPages": 0,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

Follow the customer-account reference for populated response objects, pagination, and writes.

Create an API key

Create a key for the authenticated user in this system. The first key is created through the signed-in application; this HTTP example uses an existing key.

Authentication: Active system session or an existing Read-Write system API key. All active system roles can manage their own keys; customer-account APIs separately require Owner/PrimaryOwner.

POST /api/auth/system/{systemSlug}/api-keys
x-api-key: <existing-read-write-system-key>
Content-Type: application/json

{
  "permissions": "Read-Write",
  "expiresAt": null
}

{
  "apiKey": "<new-secret-shown-once>",
  "apiKeyRecord": {
    "id": "99999999-9999-4999-8999-999999999999",
    "permissions": "Read-Write",
    "expiresAt": null,
    "createdAt": "2026-09-15T12:00:00.000Z",
    "isExpired": false
  }
}

See response object fields and error responses.

List your API keys

List the authenticated user’s keys for this system. Secrets cannot be recovered from this endpoint.

Authentication: Active system session or a Read/Read-Write system API key.

GET /api/auth/system/{systemSlug}/api-keys
x-api-key: <system-api-key>

Request body: none.

{
  "apiKeys": [
    {
      "id": "99999999-9999-4999-8999-999999999999",
      "permissions": "Read-Write",
      "expiresAt": null,
      "createdAt": "2026-09-15T12:00:00.000Z",
      "isExpired": false
    }
  ]
}

See response object fields and error responses.

Revoke an API key

Delete one of the authenticated user’s keys in the current system. The secret stops authorizing subsequent requests.

Authentication: Active system session or a Read-Write system API key.

DELETE /api/auth/system/{systemSlug}/api-keys/{apiKeyId}
x-api-key: <read-write-system-key>

Request body: none.

A missing, already revoked, or other-user key returns 400 with { "error": "API key not found." }. Keys cannot be edited or renewed. Rotate by creating a replacement, updating the integration, then revoking the old key.

{
  "success": true,
  "apiKeyId": "99999999-9999-4999-8999-999999999999"
}

See response object fields and error responses.

Response object fields

Error responses

Check the HTTP status before reading success fields. The examples use fictional data. JSON responses can contain null fields; preserve null rather than treating it as an empty string.

Ordinary error · 400

{
  "error": "API key not found."
}

Validation error · 400

{
  "error": "ValidationError",
  "issues": [
    {
      "code": "custom",
      "path": [
        "expiresAt"
      ],
      "message": "Expiration must be in the future."
    }
  ]
}

error is a string. Validation responses also contain issues, an array with code, path (field names or array indices), and message; other issue fields depend on the validation rule. Missing records use 400 and authorization failures use 401.