Workspaces API
A workspace holds connections, posts, media, API keys and members. Use several workspaces to separate brands or clients. This page covers workspace CRUD, members, invitations and role permissions. Connections are in Connections API, and API keys are in API keys and guardrails.
Auth is explained in the REST API overview. Paths below use current for the API key's workspace. To work with several workspaces from code, create one key per workspace.
Which workspace endpoints can I call?
| Method | Path | Purpose | Permission | Guarded API key |
|---|---|---|---|---|
GET | /workspaces | List workspaces you belong to | Any member | Yes |
POST | /workspaces | Create a workspace | Any signed-in user | No |
GET | /workspaces/current | Get one workspace | Any member | Yes |
PATCH | /workspaces/current | Rename | workspace.edit | No |
DELETE | /workspaces/current | Delete | workspace.delete | No |
GET | /workspaces/current/members | List members | member.view | No |
PATCH | /workspaces/current/members/:userId/role | Change a member's role | member.assign_role | No |
DELETE | /workspaces/current/members/:userId | Remove a member | member.remove | No |
POST | /workspaces/current/invitations | Invite by email | member.invite | No |
GET | /workspaces/current/invitations | List pending invitations | member.invite | No |
DELETE | /workspaces/current/invitations/:invitationId | Cancel an invitation | member.invite | No |
GET | /invitations/mine | Invitations addressed to you | Session token | No |
POST | /invitations/:token/accept | Accept | Session token | No |
POST | /invitations/:token/decline | Decline | Session token | No |
How do I list my workspaces?
curl https://api.socifyr.com/api/workspaces \
-H "Authorization: Bearer sk_..."{
"success": true,
"data": [
{
"id": "6a04f0000000000000000001",
"name": "Acme",
"slug": "acme",
"ownerId": "6a04e0000000000000000009",
"apiKeys": [
{
"id": "c51b393e-40d1-481e-94c3-042726c44ad1",
"prefix": "sk_4b7378404",
"label": "Content agent",
"createdAt": "2026-11-01T10:00:00.000Z",
"lastUsedAt": null,
"dailyPostLimit": null,
"monthlyXSpendCentsCap": null,
"requireApproval": false,
"xSpendCents": 0,
"xSpendMonth": null
}
],
"usage": { "uploadsThisMonth": 7 },
"createdAt": "2026-10-01T10:00:00.000Z",
"updatedAt": "2026-11-13T09:00:00.000Z"
}
]
}The usage object holds raw counters (shortened here). For limits and remaining amounts use Usage API. GET /workspaces/current returns one item of the same shape.
How do I create a workspace?
POST /workspaces
| Field | Type | Required | Constraints |
|---|---|---|---|
name | string | Yes | 1 to 50 characters |
curl -X POST https://api.socifyr.com/api/workspaces \
-H "Authorization: Bearer <session-token>" \
-H "Content-Type: application/json" \
-d '{ "name": "Client: Northwind" }'Returns 201 with the workspace in the shape above. The creator becomes the Owner. Creating a workspace is a user-level action, so a guarded key cannot do it.
How do I rename or delete a workspace?
PATCH /workspaces/current takes an optional name (1 to 50 characters) and returns the updated workspace. DELETE /workspaces/current returns 204.
| Status | Cause |
|---|---|
| 400 | Cannot delete your last workspace or Cannot delete the default workspace |
| 403 | Your role lacks workspace.edit or workspace.delete |
| 404 | Workspace not found |
What can each workspace role do?
Roles come from @socifyr/shared. Owner has every permission.
| Capability | Owner | Admin | Editor | Contributor |
|---|---|---|---|---|
| Create posts and drafts, view posts | Yes | Yes | Yes | Yes |
| Publish, archive, unarchive, delete posts | Yes | Yes | Yes | No |
| Approve and reject posts | Yes | Yes | Yes | No |
| Upload and view media | Yes | Yes | Yes | Yes |
| Delete media | Yes | Yes | Yes | No |
| View analytics | Yes | Yes | Yes | Yes |
| Use AI generation | Yes | Yes | Yes | Yes |
| View members | Yes | Yes | Yes | Yes |
| Invite, remove, change roles | Yes | Yes | No | No |
| Create, update, delete, view API keys | Yes | Yes | No | No |
| Edit workspace and webhooks | Yes | Yes | No | No |
| Connect and disconnect accounts | Yes | No | No | No |
| Delete workspace, manage billing | Yes | No | No | No |
How do I invite a teammate?
POST /workspaces/current/invitations
| Field | Type | Required | Constraints |
|---|---|---|---|
email | string | Yes | Valid email |
roleKey | enum | Yes | ADMIN, EDITOR, CONTRIBUTOR. OWNER is not allowed. |
curl -X POST https://api.socifyr.com/api/workspaces/current/invitations \
-H "Authorization: Bearer <session-token>" \
-H "Content-Type: application/json" \
-d '{ "email": "sam@example.com", "roleKey": "EDITOR" }'{
"success": true,
"data": {
"id": "6a05100000000000000000aa",
"email": "sam@example.com",
"roleKey": "EDITOR",
"status": "pending",
"token": "<invitation-token>",
"expiresAt": "2026-11-20T09:00:00.000Z",
"createdAt": "2026-11-13T09:00:00.000Z",
"workspace": { "id": "6a04f0000000000000000001", "name": "Acme", "slug": "acme" },
"invitedBy": { "id": "6a04e0000000000000000009", "name": "Jane", "email": "jane@example.com" }
}
}The invitee accepts with POST /invitations/:token/accept, which returns the new membership. Errors: 409 for an invitation already pending or a user who is already a member, 403 when the plan's team member limit is reached (see Limits), 400 for an invalid email or role. Accept and decline return 400 for an expired or used invitation, and 404 for an unknown one.
How do I list, change or remove members?
GET /workspaces/current/members returns an array of members:
{
"success": true,
"data": [
{
"id": "6a05200000000000000000bb",
"userId": "6a04e0000000000000000009",
"roleKey": "OWNER",
"joinedAt": "2026-10-01T10:00:00.000Z",
"user": { "id": "6a04e0000000000000000009", "name": "Jane", "email": "jane@example.com", "avatarUrl": null }
}
]
}PATCH /workspaces/current/members/:userId/role with { "roleKey": "ADMIN" } (ADMIN, EDITOR or CONTRIBUTOR) returns the updated member. DELETE /workspaces/current/members/:userId returns 204.
| Status | Cause |
|---|---|
| 400 | The workspace owner role cannot be changed, You cannot change your own role, The workspace owner cannot be removed, You cannot remove yourself from the workspace |
| 404 | Membership not found in this workspace |
GET /workspaces/current/invitations lists pending invitations in the shape above, and DELETE /workspaces/current/invitations/:invitationId cancels one (204, or 404 Invitation not found).
Frequently asked questions
How do I set up one workspace per client? Create a workspace per client, connect that client's accounts inside it, and create one API key per workspace. See Workspaces concepts.
Can an Admin connect accounts? No. Connecting and disconnecting accounts is an Owner permission.