API Keys
Create and manage API keys for integrating external systems with your workspace.
External applications authenticate with your workspace's public API through API keys. Each key targets one environment and enforces a rate limit.
How It Works
To create an API key, name it, select an environment, and optionally set a rate limit and expiration date. Itsy generates a unique key and displays it once — copy it immediately. Only a hashed version is stored.
When an external application sends an API request, it includes the key in the request header. Itsy validates the key, identifies the workspace, and enforces the rate limit.
Key Concepts
API Key Properties
| Property | Description |
|---|---|
| Name | A label for the key's purpose (e.g., "Website Integration" or "CRM Sync") |
| Environment | The API environment the key targets: Production, Preview, or Local Dev |
| Rate Limit | Maximum requests per minute (default: 60, minimum: 1) |
| Expiration | Optional date when the key becomes invalid |
| Status | Active, Expired, or Revoked |
| Last Used | Timestamp of the most recent API call with this key |
Environments
Each key targets one environment:
| Environment | Purpose |
|---|---|
| Production | Live API access for production integrations |
| Preview | Staging and testing for development |
| Local Dev | Local development and debugging |
Key Format
API keys follow the format itsy_{environment}_sk_{random}. The prefix appears in the key list for identification. The full key appears only once, at creation.
Key Security
- The full key appears only once when created or rotated — copy it immediately
- Only a SHA-256 cryptographic hash is stored in the database — the full key cannot be recovered
- The prefix (first 8 characters of the random part) is stored separately so you can identify each key in the list
- Revoke a compromised key instantly — once revoked, new requests authenticating with the key are rejected immediately. Requests already authorized and running are not forcibly terminated mid-flight; authentication is performed at request start by the
ApiKeyAuthMiddleware. - Each key records which user created it, for audit purposes
Key Lifecycle
Common Tasks
Creating an API Key
- Navigate to Settings > API Keys
- Click Create
- Enter a name
- Select the environment (Production, Preview, or Local Dev)
- Set the rate limit per minute (default: 60)
- Optionally set an expiration date for the key (leave blank for no expiry)
- Click Create
- Copy the key immediately — it will not appear again
Rotating a Key
To replace a key without changing its configuration:
- Find the key in the list
- Click Rotate Key
- Confirm — Itsy revokes the old key immediately
- Itsy generates a new key with the same name, environment, and rate limit
- Copy the new key immediately
Revoking a Key
If a key is compromised or obsolete:
- Find the key in the list
- Click Revoke
- Confirm
Itsy deactivates the key immediately and records the revocation timestamp. Integrations using it lose access. Revoked keys remain visible in the list for audit purposes but cannot be reactivated — create a new key instead.
Checking Key Usage
The Last Used column in the key list shows when each key was last used to make an API request. This timestamp updates automatically on authenticated requests. Use it to identify unused keys that may be safe to revoke, or to verify that a new integration is working.
How It Connects
- Workspace — Each API key belongs to one workspace and can access only that workspace's data. The API feature must be enabled in your workspace features.
- Workspace API — API keys authenticate requests to the Workspace API, which allows external systems to browse trips, check availability, and create orders. Every request requires the
x-api-keyheader (e.g.,x-api-key: <your-key>). See Workspace API — Authentication for full details. - Billing — Orders created through the API count against your subscription plan's order limits.