REST API: create and manage your keys

Generate API keys to connect Joinways to your tools via the REST API, and manage their permissions and revocation securely.

Updated June 4, 2026

API keys let your tools (website, request form, accounting software, external automations) communicate with Joinways securely, via the REST API. Each key is a secret credential that authenticates your requests and acts with full access to your workspace.

This article explains how to create a key, what it can reach, how to use it in your requests, then rotate or revoke it. It also serves as a reference for key scope and states.

Prerequisites

Before creating a key, make sure you have the following in place:

Admin access: only workspace admins can create, list and revoke API keys.
A Pro plan: API keys require the Pro plan; on other plans the Developers page stays disabled.
Trusted people: a key grants access to your data, so limit its creation and sharing to people who genuinely need it.

What you'll learn

Create a new API key from your settings
Understand exactly what a key can reach
Use the key in your HTTP requests
Rotate a key without downtime
Revoke a compromised key immediately

Two ways to connect Joinways

Depending on your tool, there are two paths to connect to Joinways. Pick the one that matches your case.

One-click connection (MCP) : paste the MCP server URL into your AI assistant and approve the connection — no token to copy or manage. This is the recommended path for compatible assistants.
API key (REST) : for your scripts, CLIs and custom integrations, via the REST API (base URL /api/v1). This is the focus of this article.

If your tool isn't an MCP-compatible AI assistant, the REST API key is what you need. The rest of this article walks through creating and using it step by step.

Advanced case: for a third-party app acting on behalf of a user (rather than with your own key), Joinways also exposes an OAuth 2.1 server (authorization code + PKCE). Details are in the API reference.

Create a key

Creating a key takes less than a minute. The key is shown only once, at creation: copy it before leaving the screen.

Open Settings then Developers.
Click New key, give it a clear name (e.g. "Website") and an expiration.
Set an expiration if the integration is temporary: it is your main safety net.
Copy the key shown immediately: it's only displayed once.
Store it in a secret manager, never in plain text in your code.

⚠️ Important: if you lose a key, you can't display it again. Revoke it and create a new one.

What a key can reach

This is the most important thing to know before you paste a key anywhere: a Joinways API key carries full access to the workspace it was created in. It can read AND write every resource the REST API exposes.

There is no read-only key, and no per-key permission setting. A key created to display your availability on a website can, technically, also edit a quote or delete an event.

So the protection is not a restricted scope, it is operational: one key per integration, an expiration where you can set one, storage in a secret manager, and immediate revocation at the slightest doubt.

Use the key

Once you have the key, present it on every request you send to the Joinways API. Without a valid key, the request is rejected.

Add the key to the Authorization header of your HTTP requests, as a Bearer token: Authorization: Bearer <your-key>

Every request targets the base URL /api/v1, followed by the resource path (for example events or quotes).

Build the resource URL from the base URL /api/v1.
Add the Authorization header with your key as a Bearer token.
Send the request: a valid, authorized key returns the data, otherwise an authentication error.

Read the full API reference (endpoints, schemas)

Rotate or revoke a key

Rotating a key means replacing it with a new one without interrupting service. Plan it regularly, or as soon as you have a doubt.

Create a new key following the steps above.
Deploy the new key in your integration.
Confirm everything works with the new key.
Revoke the old key once the switch is confirmed.

To revoke a key immediately (for example if it's compromised):

Go back to Settings then Developers.
Click Revoke next to the relevant key.
The key stops working immediately.

Reference: key scope and states

This section sums up what a key reaches and the states it can be in.

Scope

Full access: a key reads and writes every resource of its workspace — events, quotes, companies, contacts, catalog and more.
No per-key rights: Joinways does not offer read-only keys. Treat every key as a full-access credential.
Workspace boundary: a key never reaches another workspace's data. That is the one limit it does carry.

Key states

Active: the key is valid and accepted by the API.
Expired: the expiration date has passed; the key is rejected until it's replaced.
Revoked: the key was disabled manually and no longer works, permanently.

How it works

On each request, the API reads the key presented in the Authorization header and checks that it is active, not expired and not revoked.

If the key is valid, the API serves the request within its workspace, whatever the resource.

All actions are tied to your workspace: a key never grants access to another workspace's data.

Edge cases

Multiple integrations: create a separate key per integration rather than sharing a single one, so you can revoke one without breaking the others.
Key without expiration: if your integration runs continuously, still plan a regular rotation to limit exposure.
Team change: when someone leaves the project, revoke the keys they may have known and create new ones.

💡 Tip: name your keys after their use ("Website", "Accounting", "Zapier") to instantly identify which one to revoke if something goes wrong.

Security best practices

An API key is a secret, just like a password. A few simple rules dramatically reduce the risks.

One key per use: easier to revoke without breaking everything.
Never in plain text: store your keys in a secret manager, not in code or a Git repository.
Never share a key: by email or chat; pass it through a secure channel if needed.
One key, one integration: since you cannot restrict a key's rights, isolating uses is what limits the blast radius of a leak.
Expiration and rotation: set an expiration and immediately revoke any key you suspect.

Troubleshooting

Here are the most common problems, their likely cause and the solution.

The request returns an authentication error (401)

Cause: the key is missing, malformed, expired or revoked.
Solution: check the Authorization header (Bearer token), then the key's state on the Developers page; if it's expired or revoked, create a new one.

The request is rejected (403)

Cause: the workspace is no longer on the Pro plan, or the resource is out of reach for this workspace.
Solution: check the workspace's plan, then that the resource you are targeting does belong to it. A key's rights cannot be adjusted: they are always full access to its own workspace.

Can't find the value of an existing key

Cause: a key is shown only at creation and is never stored in plain text.
Solution: revoke the old key and create a new one, then update your integration.

Examples

Example 1 — Display availability on a website

You create a key named "Website", store it on your site's SERVER (never in the page's JavaScript, where any visitor could read it), then query the API to display your available slots. Remember that this key could also write: if the site is compromised, revoke it immediately.

Example 2 — Sync an automation

You create a "Zapier" key, paste it into your automation tool, then schedule a rotation every three months. The day you switch tools, you revoke the old key without affecting your other integrations.

FAQ

Where can I find the API documentation?

The full reference (endpoints, schemas, examples) is available on the Joinways API reference, accessible via the "View documentation" button on the Developers page or the link below.

Are API keys included in all plans?

No: they require the Pro plan.

How many keys can I create?

You can create several keys, one per use or integration. It's even recommended, so you can revoke one without affecting the others.

What happens if I lose a key?

A lost key can't be displayed again. Revoke it and create a new one, then update your integration.

Does a key grant access to other workspaces' data?

No. A key only acts within the workspace where it was created — but within that workspace, it reaches everything.

Should I rotate keys regularly?

Yes, it's a good practice. Rotation limits a key's exposure over time, even without a known incident.

Who can create or revoke keys?

Only workspace admins, on a Pro plan, can manage API keys.