Which FyneDesk plan includes the Public API?

Creating and using Public API keys requires the Business plan. Teams on other plans can view the API area in FyneDesk, but cannot create keys.

Can I create a read only API key?

Yes. Give the key only read scopes for the resources it needs. Write and delete access are separate scopes, so a read only key cannot change or remove data.

How do I rotate an API key?

Open Settings, then Developer & Data, then API Keys. Choose the key and select Rotate. FyneDesk issues a new token and revokes the old token.

Are changes made through the API audited?

Yes. Changes made through the API appear in the same ticket activity history as changes made in FyneDesk, including deletions.

When should I use webhooks instead of the API?

Use the API when your system needs to read, create, or update FyneDesk data. Use webhooks when your system needs a real time notification that an event happened in FyneDesk. Many integrations use both.

FyneDesk Public API

Connect FyneDesk to the systems your team already uses. The Public API lets approved integrations read and update workspace data without manual exports or duplicate entry.

What you can build

The FyneDesk Public API is a REST API that uses JSON over HTTPS. It gives your integration programmatic access to tickets, contacts, companies, knowledge base articles, assets, and calendar data in your workspace.

You might use it to create tickets from another system, keep customer records in sync, build internal reporting, or connect FyneDesk to a workflow your team already depends on.

Use the in app reference for implementation details The API Reference in FyneDesk is the source of truth for current endpoint paths, request fields, response fields, and available scopes. This guide explains how the API works and how to use it safely.

Who can use the Public API

Creating and managing API keys requires the Business plan. Teams on lower plans can still view the API area, but FyneDesk keeps key creation locked until the workspace upgrades.

Only an Admin with the security-management permission can manage keys. In FyneDesk, go to Settings → Developer & Data → API Keys.

That area includes two tabs:

API Keys lets an Admin create, rotate, revoke, scope, and set expiry for keys.
API Reference shows the current endpoint list, required scopes, per key usage, and recent requests.

Quick start

1 Open Settings → Developer & Data → API Keys.
2 Create a key with a clear name, such as "Reporting connection" or "Customer sync".
3 Choose only the scopes the integration needs and set an expiry that fits its purpose.
4 Copy the key and store it in your secret manager. FyneDesk shows the full value only once.
5 Open the API Reference tab to choose the endpoint and request format for your first integration.

Keep the key somewhere safe API keys start with fdk_. FyneDesk stores only a protected hash, so the full key cannot be shown again after creation. If you lose it, rotate the key and update your integration.

Authentication

Send your API key with every request as a bearer token:

Authorization: Bearer fdk_...

Responses are JSON. When a request cannot be completed, FyneDesk returns JSON with an HTTP status, an error code, and a message that explains what went wrong.

Choose the right scopes

Scopes follow a simple resource:action format. Give each key the smallest set of permissions it needs.

read lets an integration view data.
write lets an integration create and update data.
delete is separate because removing records is destructive. It is never included with write access.

Available resources include tickets, contacts, companies, knowledge base articles, assets, and calendar data. For example, a reporting connection may need only tickets:read, while a customer sync might need contacts:read and contacts:write.

Start with less access Keep delete scopes off unless the integration truly needs to remove records. A narrowly scoped key limits the impact of a configuration mistake or exposed secret.

What the API can access

Tickets can be listed, filtered, searched, created, updated, and deleted. Ticket comments support public replies and internal notes, and posting an internal note requires write access.
Contacts and companies can be read, created, updated, and deleted.
Knowledge base articles can be read, created, and updated.
Assets can be read, created, and updated.
Calendar data can be read.

The API Reference shows the exact operations and scopes for each resource.

Make changes safely

Use an Idempotency-Key header on create, update, and delete requests. This lets your integration retry a request safely after a network problem without accidentally creating duplicate records.

FyneDesk accepts only approved writable fields. Relationship fields, such as an assignee or category, are checked to make sure they belong to the same workspace.

Every API change is recorded in the ticket activity history, just like a change made in the FyneDesk interface. Tickets created through the API are also marked as API sourced.

Pagination, limits, and errors

List responses use cursor pagination. Each response includes the cursor you need to request the next set of results, helping your integration move through large lists consistently.

The current default rate limit is 120 requests per minute per key. FyneDesk returns limit, remaining, and reset details with requests. If a key goes over its limit, the API returns HTTP 429. Check the in app API Reference for the live limit before relying on a number in production.

Common response statuses include 200 and 201 for success, 400 for an invalid request, 401 for an invalid key, 403 for a missing permission, 404 when a record cannot be found, 429 for rate limiting, and 500 for an unexpected error.

Use webhooks for real time events

The API is useful when your system needs to request or change FyneDesk data. Outbound webhooks are useful when your system needs FyneDesk to tell it that something happened.

Webhooks can send signed events for ticket, contact, and company activity to your HTTPS endpoint. FyneDesk also supports managed webhook destinations for HubSpot and Zulip. Delivery logs, test events, redelivery, and automatic disabling after repeated failures help you operate integrations with confidence.

Webhooks are available on Pro and Business. Learn more in Webhooks & Integrations.

Security and key management

Set a key expiry when you can. You can choose 30, 90, or 365 days, Never, or a custom date.
Rotate keys on a regular schedule and immediately after a suspected leak. Rotation creates a new token and revokes the old one.
Revoke a key at any time to stop it immediately.
Store keys in a secret manager or protected environment variable. Do not place them in browser code, screenshots, or source control.
Each key is limited to its own workspace. It cannot read or write another FyneDesk workspace.

FyneDesk also throttles repeated failed authentication attempts. The current default is 20 failed attempts within five minutes from one IP address. Check the API Reference for the current behavior.

Frequently asked questions

Which plan do I need?

The Public API and API key creation require Business. Outbound webhooks are available on Pro and Business.

Can I make a key read only?

Yes. Select only read scopes for the resources your integration needs. Write and delete permissions are separate.

How do I rotate a key?

Open Settings, then Developer & Data, then API Keys. Choose the key and select Rotate. Update your integration with the new token because the old token stops working.

Are API changes audited?

Yes. API activity appears in the same history your team uses to understand who changed what and when, including deletions.

Should I use the API or webhooks?

Use the API to read or change FyneDesk data. Use webhooks when you need a real time notification that something changed. Most connected systems use both.

Next steps

Open Settings in FyneDesk, then go to Developer & Data → API Keys to create a key or open the API Reference. You can also review Webhooks & Integrations and FyneDesk plans.