Full Engage

Learn how to create and use API keys to access the REST API from external clients.

Overview

API keys allow external clients (mobile apps, scripts, server-to-server integrations) to access the REST API without browser-based session authentication.

Each API key is:

User-scoped — actions are attributed to the user who created the key
Organization-scoped — the key only has access to data within the organization it was created in
Time-limited — keys have a required expiration date

Creating an API Key

Navigate to Settings in your organization dashboard
Select the API Keys tab
Click Create Key
Enter a descriptive name (e.g., "Mobile App", "CI/CD Pipeline")
Select an expiration period (30 days, 60 days, 90 days, 1 year, or custom)
Click Create

The API key is only shown once after creation. Copy it immediately and store it securely.

Using an API Key

Include the API key in the Authorization header of every request:

Authorization: Bearer ba_<your-api-key>

Token Format

API keys use the format ba_ followed by 40 hexadecimal characters:

ba_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9

The ba_ prefix enables automated secret scanning tools (e.g., GitHub, GitGuardian) to detect leaked keys.

Key Lifecycle

State	Description
Active	Key is valid and can be used for authentication
Expired	Key has passed its expiration date and is automatically rejected
Revoked	Key has been manually revoked by the user and is permanently disabled

Revoking a Key

To revoke a key, go to Settings > API Keys and click Revoke next to the key. Revocation is immediate and irreversible.

Response Format

All successful responses follow this format:

{
  "data": { ... },
  "total": 42
}

data: The resource or array of resources
total: Total count (only in list endpoints, for pagination)

Error Responses

Status	Reason
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing, invalid, expired, or revoked API key
`404 Not Found`	Resource does not exist or belongs to another organization
`422 Unprocessable Entity`	Validation error (details in response body)
`500 Internal Server Error`	Unexpected server error

Validation errors (422) include details:

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "email": ["Invalid email address"]
    },
    "formErrors": []
  }
}

Security Best Practices

Never commit API keys to source control
Store keys in environment variables or a secrets manager
Use short expiration periods when possible
Revoke keys immediately if they may have been compromised
Create separate keys for different applications or environments
Monitor usage via the "Last Used" column in the API Keys settings

Authentication