API reference | Memberships

Method	Path	Summary
GET	…/memberships	List workspace memberships
PATCH	…/memberships/{membershipId}	Update a workspace membership
POST	…/memberships/{membershipId}/disable	Disable a workspace membership

Paths start with /workspaces/{workspaceId}. GET endpoints need memberships:read, the others memberships:write.

The Membership object

firestoreIdstringrequired

ID of the membership, the same as the user ID of the member.

workspaceIdstringrequired

ID of the workspace.

userIdstringrequired

ID of the user.

displayNamestringrequired

emailstringemailrequired

photoUrlstringuri

rolestringrequired

Role of the user, which sets its permissions in a workspace (ws.) or a billing account (ba.).

ws.owner
Owner of the workspace, with every permission, including deleting the workspace and managing owners.
ws.admin
Administrator of the workspace, with every permission except managing owners and deleting the workspace or its files.
ws.member
Member of the workspace, who works on its transactions, invoices, payments and accounting but manages neither its bank accounts nor its members.
ws.viewer
Viewer of the workspace, a role that grants no permission.
ws.support
Sway support access, granted when you invite the Sway bot.
ba.owner
Owner of the billing account, with every permission, including deleting it.
ba.admin
Administrator of the billing account, who reads and updates it but cannot delete it.
ba.member
Member of the billing account, who can only read it.

Show all 8 fields

activationobjectrequired

Whether the resource is enabled, and when and by whom it was last enabled or disabled.

Show 3 child fields

enabledbooleanrequired

Whether the resource is enabled.

updateDateTimestringdate-timerequired

Date and time when enabled was last set.

updatedBystring

ID of the user who last set enabled, when recorded.

The Membership object

{
  "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
  "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
  "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
  "displayName": "string",
  "email": "anna.meier@example.com",
  "photoUrl": "https://example.com",
  "role": "ws.owner",
  "activation": {
    "enabled": true,
    "updateDateTime": "2026-03-02T09:15:00.000Z",
    "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
  }
}

GET/workspaces/{workspaceId}/memberships

List workspace memberships

Scopememberships:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

limitinteger

Maximum number of items to return, from 1 to 100. A missing, invalid or non-positive value falls back to 20, and a larger value to 100.

Default20

startAfterstring

Cursor of the page to return: the nextCursor of the previous page.

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

idsstring[]

Comma-separated IDs of the items to return, up to 30. When set, limit, startAfter and the filters are ignored.

Returns

200

List of items

dataMembership[]required

Items of the page, in list order.

limitintegerrequired

Page size of the request, or the number of requested ids.

nextCursorstring

Cursor of the next page, to pass as startAfter. Absent when the page holds fewer items than limit; a full last page still has one, and the page it points to is empty.

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": [
    {
      "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
      "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
      "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
      "displayName": "string",
      "email": "anna.meier@example.com",
      "photoUrl": "https://example.com",
      "role": "ws.owner",
      "activation": {
        "enabled": true,
        "updateDateTime": "2026-03-02T09:15:00.000Z",
        "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
      }
    }
  ],
  "limit": 0,
  "nextCursor": "string"
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

PATCH/workspaces/{workspaceId}/memberships/{membershipId}

Update a workspace membership

Scopememberships:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

membershipIdstringrequired

ID of the membership, the same as the user ID of the member.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

rolestringrequired

Valuesws.ownerws.adminws.memberws.viewerba.ownerba.adminba.member

Returns

200

Successful response

dataMembershiprequired

curl -X PATCH 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "ws.owner"
}'

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "role": "ws.owner"
  }),
});
console.log(await response.json());

import os

import requests

response = requests.patch(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
    json={
        "role": "ws.owner",
    },
)
print(response.json())

{
  "data": {
    "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "displayName": "string",
    "email": "anna.meier@example.com",
    "photoUrl": "https://example.com",
    "role": "ws.owner",
    "activation": {
      "enabled": true,
      "updateDateTime": "2026-03-02T09:15:00.000Z",
      "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    }
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

POST/workspaces/{workspaceId}/memberships/{membershipId}/disable

Disable a workspace membership

Scopememberships:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

membershipIdstringrequired

ID of the membership, the same as the user ID of the member.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Returns

200

Successful response

dataMembershiprequired

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj/disable' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj/disable', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.post(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/memberships/Xq3vT9mB2kLpR7sN4wYc8dZf1aHj/disable",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "firestoreId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "userId": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj",
    "displayName": "string",
    "email": "anna.meier@example.com",
    "photoUrl": "https://example.com",
    "role": "ws.owner",
    "activation": {
      "enabled": true,
      "updateDateTime": "2026-03-02T09:15:00.000Z",
      "updatedBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    }
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

Cookies, with your consent

Memberships

The Membership object

List workspace memberships

Path parameters

Query parameters

Returns

Update a workspace membership

Path parameters

Query parameters

Request body

Returns

Disable a workspace membership

Path parameters

Query parameters

Returns

Start building on your own data.