API Keys

API keys allow external systems and scripts to authenticate with The One Stack APIs. Keys are managed centrally in Hub and can be scoped to specific products.

Creating an API Key

1. Go to Hub > Settings > API Keys.
2. Click New API Key.
3. Enter a descriptive name (e.g., "Zapier Integration" or "Reporting Script").
4. Select the product scopes — choose which product APIs this key can access.
5. Optionally set an expiration date. Keys without an expiration remain active until manually revoked.
6. Click Create.

caution

The full API key is only shown once at creation time. Copy it immediately and store it securely. You will not be able to view the full key again.

Product Scopes

Each API key can be scoped to one or more products:

Scope	Grants Access To
PSA	Tickets, boards, time entries, contacts, companies
CRM	Contacts, companies, deals, activities
Books	Invoices, payments, entities, chart of accounts
RMM	Devices, scripts, patch policies, alerts
Security	Alerts, rules, incidents, MITRE mappings
Defend	Endpoints, detections, response actions
Backups	Jobs, schedules, restore points
Voice	Call logs, recordings, contacts
Portal	Client users, portal settings
Hub	Tenants, users, roles, entity sync, workflows

A key with no scopes selected has no access. Always follow the principle of least privilege and only grant the scopes your integration requires.

Using API Keys

Include the API key in the Authorization header of your HTTP requests:

Authorization: Bearer tos_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

All API keys are prefixed with tos_ for easy identification.

Example Request

curl -H "Authorization: Bearer tos_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://api.theonepsa.com/api/tickets

See the API Reference for endpoint documentation and request/response schemas.

Rotating Keys

To rotate an API key without downtime:

1. Create a new API key with the same scopes.
2. Update your integration to use the new key.
3. Verify the integration works with the new key.
4. Revoke the old key.

This approach avoids any gap in access during the transition.

Revoking Keys

1. Go to Hub > Settings > API Keys.
2. Find the key you want to revoke.
3. Click the Revoke button.
4. Confirm revocation.

Revoked keys are immediately invalid. Any requests using a revoked key will receive a 401 Unauthorized response.

Viewing Usage

Each API key tracks usage metrics:

• Last used — Timestamp of the most recent request.
• Total requests — Cumulative request count since creation.
• Requests (30 days) — Request count for the last 30 days.
• Error rate — Percentage of requests that returned 4xx or 5xx status codes.

View usage from Hub > Settings > API Keys by clicking on any key.

Rate Limits

API keys are subject to rate limiting:

Tier	Requests per minute	Burst limit
Standard	60	100
Professional	300	500
Enterprise	1000	2000

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1711234567

When rate limited, the API returns 429 Too Many Requests. Wait until the reset time before retrying.

Security Best Practices

• Never commit API keys to source control. Use environment variables or a secrets manager.
• Scope keys narrowly. Only grant access to the products your integration needs.
• Set expiration dates for keys used by temporary integrations or contractors.
• Rotate keys regularly — at minimum every 90 days for production integrations.
• Monitor usage and revoke keys that show unexpected activity.
• Use separate keys for each integration so you can revoke one without affecting others.