Authentication

Every request to the Sway API goes over HTTPS to the base URL, https://api.business.swayapp.io/v1, and carries an API key in its Authorization header. The key acts on behalf of the user who created it: it reaches the workspaces that this user belongs to, with the rights of their role in each. Only GET /health answers without a key.

Before you start

• A licence that includes the Sway API. The base licence covers the whole platform; a higher tier adds the public API. Contact Sway to add it.
• An API key. In the web app, choose your name at the bottom of the sidebar, then Profile, Developer and Create API key: Developer and API keys explains each field of the dialog.

Send the key

Keep the key in an environment variable, never in your code, and send it as a bearer token:

export SWAY_API=https://api.business.swayapp.io/v1
curl "$SWAY_API/workspaces" \
-H "Authorization: Bearer $SWAY_API_KEY"

• A key starts with sway_. The web app shows it once, when you create it: Sway stores only a digest of the key, so no one can show it to you again.
• The header takes the word Bearer, with a capital B, then one space and the key.
• A missing, unknown, revoked or expired key gets 401 unauthenticated, with the same message in each case.

Scopes

A scope lets a key use one resource of the API, and reads resource:verb:

• read covers the GET endpoints of the resource, such as listing or searching the invoices.
• write covers every other method: create, change, delete, and actions such as an export. It does not include read.
• resource:* grants both. *:*, Full access in the web app, grants every resource, including those that the API adds later.

A call without the scope that it needs gets 403 permission-denied, with the scope in its message, such as Missing required scope: invoices:read. The scope decides which endpoints a key may call; the role of its user in each workspace still decides which data it reads and what it may change.

Each scope covers the pages of the reference in its row:

Expiry

A key expires 30, 60 or 90 days after you create it, on a date that you choose, or never; the web app starts on 30 days. Once expired, a key gets 401, like an unknown one, so plan its replacement before that date.

Replace a key

A key cannot be renewed: you replace it with a new one, with no interruption for your software.

1. Create the new key. Give it the same scopes, and a name that tells it apart from the old one.
2. Switch your software to it. Deploy the new key, then check that its calls succeed.
3. Revoke the old key. In Profile › Developer, choose Revoke on its row. The revocation takes effect at once and cannot be undone.

Keys and workspaces

• A key reaches every workspace of its user, with the rights of their role in each. A scope cannot limit it to one workspace.
• When the subscription of a workspace has ended, every call on its data answers 409, reads included: see Errors.

To let Claude read your workspaces with a key, see Claude connector.