API tokens and developer access

Updated Oct 20, 20266 min read

English

On this page

API tokens give code or scripts a way to talk to your Deskwoot account without using a password. You generate one per integration (a CRM sync, a custom dashboard, an internal tool) and scope it to only the permissions that integration actually needs. Tokens can be revoked anytime; revoking is instant and doesn't affect any other token. Base URL is https://deskwoot.com/api/v1/ and the auth header is Authorization: Bearer YOUR_TOKEN. API access is Enterprise-only; pre-existing tokens from older plans keep working until expiry.

Deskwoot provides a REST API that gives you programmatic access to your support data and workflows. Whether you are building custom integrations, syncing ticket data with internal tools, or automating repetitive tasks, API tokens let you authenticate securely without sharing your login credentials. This guide walks you through generating tokens, making your first API call, and following the practices that keep your account safe.

The REST API is an Enterprise feature. The 7-day Enterprise trial that every new account starts on does not include API tokens; you need an active Enterprise plan to create and use them. If you are on a lower plan and need API access, you will need to be on Enterprise. For a fuller picture of what the API covers, see the REST API overview.

How do I generate an API token?

Log in to your Deskwoot account and go to Settings > API Tokens.
Click Create token. Only administrators can create tokens.
Give the token a descriptive name (for example CRM sync, production) so you can identify its purpose later.
Select the specific permission scopes the token should have. Grant only the access levels your integration actually needs. Optionally pick an expiration date.
Confirm and copy the token immediately. For security reasons, the full token is shown only once.

How do I use the API?

All API requests are made against the following base URL:

https://deskwoot.com/api/v1/

Include your API token in the Authorization header of every request:

Authorization: Bearer YOUR_TOKEN

Example request

A simple cURL call to test your connection might look like this:

curl -H "Authorization: Bearer YOUR_TOKEN" https://deskwoot.com/api/v1/me

If the token is valid, the API returns your account ID and the token's scopes. If not, you get an authentication error. The full endpoint reference is in the API docs.

What are the best practices?

Grant the least access needed. Assign each token only the permissions it requires. Avoid creating tokens with full admin access unless you genuinely need it.
Rotate tokens regularly. Periodically revoke old tokens and generate new ones, especially when team members change roles or leave.
Store tokens securely. Keep tokens in environment variables or a secrets manager. Never hard-code them in client-side code or commit them to version control.
Use descriptive names. Naming tokens after the integration or environment they serve makes auditing straightforward.
Monitor usage. Review your active tokens in Settings > API Tokens on a regular basis and delete any that are no longer in use.

How do I troubleshoot token errors?

401 Unauthorized: Double-check that the token is copied correctly, has not been revoked, and is included in the header with the Bearer prefix.
403 Forbidden: The token may lack the permissions for the endpoint you are calling. Create a new token with the right scopes and revoke the old one. A 403 also appears when the workspace is no longer on the Enterprise plan.
Rate limiting: If you receive rate-limit errors, reduce how often you call the API or add exponential back-off to your code.

Frequently asked questions

What if I want an AI agent to use the helpdesk instead?

If you want an external AI agent to operate Deskwoot rather than building your own integration, look at the MCP server. It is also an Enterprise feature and uses scoped bot tokens.

Where do I create an API token?

Settings → API Tokens → Create token. Pick a descriptive name, select scopes, copy the token once it's shown. The token is only displayed once for security reasons. We store only a SHA-256 hash on our side, never the raw token.

What scopes are available?

In Settings → API Tokens you can pick read (everything), write (everything), the narrower pairs contacts:read, contacts:write, conversations:read, conversations:write, help_center:read, help_center:write, and inbound:ingest (pushing messages into a REST API channel inbox, not covered by write). Pick the narrowest that the integration actually needs.

What happens if I lose a token?

Revoke it and create a new one. There's no recovery; the token value isn't stored in a recoverable form on our side either, that's intentional.

Which plans get API access?

Enterprise. Tokens created on older plans before the 2026-05 pricing migration keep working until they expire (the legacyApiAccess flag in the token record lets them through), but new tokens require Enterprise. The 7-day trial does not include API tokens.

Can I scope a token to a single inbox or team?

Not at the scope level. Workaround: filter every request to that inbox or team's IDs on your side.

Are tokens user-bound or account-bound?

Both: a token is tied to one user inside one account. Token actions are attributed to the creating user. Each member sees and revokes only their own tokens, and removing someone from the workspace does not revoke their tokens, so have them revoke their tokens before they leave. Best practice for shared integrations: have a dedicated 'API' service-account user own integration tokens.

How do I rotate tokens safely without downtime?

Create the new token, deploy it everywhere, leave the old one active for a deploy cycle, then revoke. The two tokens work in parallel during the window so nothing breaks.

Does the API count toward my AI conversations quota?

No. Reading conversations, posting agent replies, or managing contacts through the API does not use AI conversations. AI conversations are used when Fynn or Copilot works on a conversation.

Can I use the API from the browser?

Technically yes, but don't put tokens in client-side code: anyone viewing the source can steal them. Browser-side calls should go through your own backend that holds the token.

Can I set an expiry on a token?

Yes. Pick a date under Expiration (optional) when creating the token; the token works until the end of that day in your time zone and is rejected on every call after that. Useful for short-lived integrations (an audit, a one-off migration script) so you don't have to remember to clean up.

Can I get webhooks instead of polling?

Yes. Settings → Webhooks → subscribe to events (new conversation, new message, status change, etc.). Each delivery is HMAC-signed (X-Deskwoot-Signature header); verify the signature before processing.

Is the REST API available on all plans?

No. The REST API is an Enterprise feature. Lower paid plans do not include it, and neither does the 7-day Enterprise trial: API tokens need an active Enterprise plan.

Can I create multiple API tokens?

Yes. You can generate as many tokens as you need. A separate token for each integration or environment is recommended, so you can revoke one without affecting the others.

What happens if my token is compromised?

Go to Settings > API Tokens immediately, revoke the compromised token, and generate a new one. Then update any services that relied on the old token.

Where do I create a token?

Under Settings > API Tokens. Name the token, grant only the scopes it needs, and copy it right away since the full value is shown only once.

Was this guide helpful?

Keep reading

Ask Fynn about this guide

Get a short answer from this guide and the rest of the help center.