API Keys

API keys are how external systems prove they're allowed to call Workestra's public ticket API. Each key carries a set of scopes that define what it can do — read tickets, create tickets, read contacts, write contacts. Keys are scoped to a single workspace.

Use API keys when:

• A backend service needs to create or query tickets programmatically
• A scheduled job needs to sync tickets to a data warehouse
• A custom dashboard needs to read ticket counts
• An external form (not the embeddable widget) needs to submit tickets

For the customer-facing widget and portal, you don't need API keys — those use one-time magic-link tokens automatically.

Creating a Key

1. Go to Support > Settings > API Keys
2. Click Create API Key
3. Fill in the form:

4. Click Create
5. Copy the key from the dialog — it's shown only once

The key looks like this:

wks_live_a1b2c3d4e5f6g7h8...

Treat it like a password. Anyone with the key can act with the scopes you granted.

Scopes

Pick the smallest set of scopes that lets your integration do its job:

A read-only sync job needs only tickets.read. A form-to-ticket integration needs tickets.write. A full CRM bridge needs both write scopes.

Using the Key

Send the key in the Authorization header on every request:

GET /api/public/tickets
Authorization: Bearer wks_live_a1b2c3d4e5f6...

Workestra responds with 401 Unauthorized if the key is missing, malformed, or revoked, and 403 Forbidden if the key is valid but doesn't have the required scope for the endpoint.

See Developer API for the full endpoint list and request/response shapes.

Managing Keys

Last Used

Each key shows a Last used timestamp on the API Keys page. Use it to spot keys that haven't been used in months — those are usually safe to revoke.

Renaming

You can rename a key at any time without breaking integrations. The key value stays the same.

Revoking

To stop a key from working immediately:

1. Find the key in the list
2. Click the trash icon
3. Confirm the revocation

The key is invalidated within seconds. Any in-flight integration using it starts receiving 401 Unauthorized on its next call.

Rotation

Workestra doesn't support in-place rotation. To rotate:

1. Create a new key with the same scopes
2. Update your integration to use the new key
3. Confirm the integration is healthy
4. Revoke the old key

This avoids the brief window of ambiguity that a "swap the secret in place" flow would create.

Rate Limits

API keys share the same per-IP rate limits as anonymous public-API calls:

If your integration legitimately needs higher limits, contact support — workspace-level rate-limit overrides are available on request.

Security Best Practices

• Store keys in a secrets manager, not in source code or environment files committed to git
• Use one key per integration, not a shared "company key". Easier to revoke when an integration goes away
• Use the smallest scope that lets the integration work
• Rotate after any departures — when a teammate leaves, revoke any key they had access to
• Watch the Last used column — a key not used in 90 days is a candidate for revocation

When NOT to Use an API Key

• For the embeddable widget — it uses an unauthenticated public endpoint with workspace ID, no key needed
• For customer portal access — customers receive magic-link tokens via email
• For agent-facing UI work inside Workestra — agents authenticate with their own session
• For inbound email — configure an email processor instead

Next Steps

• Developer API — Endpoint reference and authentication
• Webhooks — Receive events instead of polling
• Widget — Embed without an API key