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
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 of its creator's role, within 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:
- The "Owner" or "Admin" role: only they see the "Developers" page and can create, rename and revoke API keys. A key acts with the rights of its creator's role.
- A Pro plan, or the trial period: on other plans, the "Developers" page invites you to upgrade to Pro.
- 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, with 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, refresh tokens). The app then acts with the rights of the role of the user who approves it. 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", fill in the "Key name" (e.g. "Website") and pick an "Expiration": "Never expires", "30 days", "90 days" or "1 year". If the integration is temporary, set an expiration: it is your main safety net. Click "Create key".
- 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.
The "Your API keys" list shows each key's prefix, creation date, last use and expiration. An expired key is flagged. The pencil icon renames it without changing its value.
What a key can reach
This is the most important thing to know before you paste a key anywhere: a Joinways API key acts with the rights of its creator's role, in the workspace it was created in. Since only the owner and admins create keys, a key can in practice read AND write every resource the REST API exposes. If its creator's role changes (for example an admin moved back to member), the key's rights follow immediately.
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 proposal 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 https://joinways.app/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.
Every response shows your quota in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. On the Pro plan, a workspace can send 600 requests per minute and 100,000 per day (200 per minute and 5,000 per day during the trial). Beyond that, the API returns 429 with a Retry-After header telling you when to resume.
To replay a write without risking a duplicate (after a network drop, for example), add an Idempotency-Key header with a unique value: for 24 hours, the same value returns the same response without performing the action again.
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 the trash icon ("Revoke key") next to the relevant key. No confirmation is asked.
- The key stops working immediately and disappears from the list.
Reference: key scope and states
This section sums up what a key reaches and the states it can be in.
Scope
- Creator's rights: a key reads and writes what its creator's role allows (events, proposals, companies, contacts, catalog and more). With an owner or admin role, that is the whole workspace.
- No per-key rights: Joinways does not offer read-only keys. Treat every key as carrying all of its creator's rights.
- Workspace boundary: a key never reaches another workspace's data.
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, within the rights of its creator's role. An action that role does not allow returns a 403 error.
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: a key is tied to the member who created it and carries the rights of their role. If that role changes, the key's rights follow; if that member is removed from the workspace, their keys stop working. Create keys for long-lived integrations from an account that will stay, and revoke those a departing person may have known.
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.
- 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 key looked valid but the request returns 401, 403 or 404
- Cause: 401 if the member who created the key left the workspace; 403 if the workspace no longer has the Pro plan or the trial; 404 if the resource does not belong to this workspace.
- Solution: check that the key creator is still a member of the workspace, otherwise create a new key from an active account; for a 403, check the workspace plan; for a 404, check the resource ID.
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.
The request returns a permission error (403)
- Cause: the role of the person who created the key does not allow this action. For example, an Operations role reads neither requests nor proposals, and a Read-only role writes nothing.
- Solution: check their role in Settings then Teammates, or create the key from an owner or admin account.
The request returns a conflict (409)
- Cause: the action does not match the record's state, for example editing an archived event or a signed proposal. The error.details.reason field gives the reason.
- Solution: read that reason and adjust the request, for example restore the archived event (POST /api/v1/events/{id}/unarchive) before editing it.
The request returns too many requests (429)
- Cause: the workspace quota is reached (600 requests per minute and 100,000 per day on the Pro plan).
- Solution: wait for the delay given by the Retry-After header, then space out or batch your calls.
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.
Two routes serve this. GET /api/v1/venues/{venueId}/availability returns the opening hours, closures and enforcement mode of the venue or of a space. GET /api/v1/venues/{venueId}/conflicts returns the events already taking the venue or the requested spaces over a period, accounting for combined spaces and set-up and tear-down times, along with the closures and the days the venue does not open.
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.
Example 3: Read the detail of a platform proposal
A proposal that came from a platform has a single amount line. GET /api/v1/quotes/{id} also returns document_lines, the lines read from its PDF, and document_lines_status, the state of the reading. These lines are read-only and count in no total. document_lines is null until the PDF has been read, and on a Joinways proposal.
FAQ
Where can I find the API documentation?
The full reference (endpoints, schemas, examples) is available through the "API documentation" link, top right of the "Developers" page, or the link below.
Are API keys included in all plans?
No: they require the Pro plan (or the trial period).
How many keys can I create?
Up to 10 active keys per workspace, one per use or integration. Beyond that, revoke older keys before creating new ones.
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, with the rights of its creator's role.
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 the workspace owner and admins, on a Pro plan or during the trial, can manage API keys.
See also
Ready to centralize your event inquiries?