Create and manage your API keys

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

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 the rights you grant it.

This article explains how to create a key, scope it to the right permissions, use it in your requests, then rotate or revoke it. It also serves as a reference for key permissions 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 API tab 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
Scope a key to the right permissions
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.

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 Integrations, API tab.
Click New key, give it a clear name (e.g. "Website") and an expiration.
Review the permissions granted before confirming (see the dedicated section below).
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.

Scope the key (permissions)

Before confirming creation, check what the key will be able to do. A key inherits the rights you grant it: the broader they are, the riskier a leak.

Give each key the minimum rights its use requires. A key meant to display your availability on a website, for example, doesn't need to be able to edit quotes.

We generally distinguish read rights (viewing data) from write rights (creating or editing data). Reserve write access for integrations that truly need it.

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 Integrations, API tab.
Click Revoke next to the relevant key.
The key stops working immediately.

Reference: key permissions and states

This section sums up the permissions a key can carry and the states it can be in.

Permissions

Read: allows viewing data (for example listing events or quotes) without being able to modify it.
Write: allows creating and editing data; reserve it for integrations that need it.
Scope: a key only acts within your workspace and according to the rights granted at creation.

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 then checks it has the permissions required for the requested action, and returns the data.

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.
Grant minimum rights: only give write access to integrations that need it.
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 in the API tab; if it's expired or revoked, create a new one.

The request is rejected (403) even though the key is valid

Cause: the key doesn't have the permissions required for the requested action.
Solution: use a key with the necessary rights (for example write access to create data), or recreate the key with the right permissions.

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 read-only key named "Website", store it on your site's server, then query the API to display your available slots. If it leaks, the key can only read, never modify your data.

Example 2 — Sync an automation

You create a "Zapier" key with the rights it needs, 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 in the API tab 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 and according to the rights granted to it.

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.