Skip to content

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? ​

MethodPathPurposePermissionGuarded API key
GET/workspacesList workspaces you belong toAny memberYes
POST/workspacesCreate a workspaceAny signed-in userNo
GET/workspaces/currentGet one workspaceAny memberYes
PATCH/workspaces/currentRenameworkspace.editNo
DELETE/workspaces/currentDeleteworkspace.deleteNo
GET/workspaces/current/membersList membersmember.viewNo
PATCH/workspaces/current/members/:userId/roleChange a member's rolemember.assign_roleNo
DELETE/workspaces/current/members/:userIdRemove a membermember.removeNo
POST/workspaces/current/invitationsInvite by emailmember.inviteNo
GET/workspaces/current/invitationsList pending invitationsmember.inviteNo
DELETE/workspaces/current/invitations/:invitationIdCancel an invitationmember.inviteNo
GET/invitations/mineInvitations addressed to youSession tokenNo
POST/invitations/:token/acceptAcceptSession tokenNo
POST/invitations/:token/declineDeclineSession tokenNo

How do I list my workspaces? ​

bash
curl https://api.socifyr.com/api/workspaces \
  -H "Authorization: Bearer sk_..."
json
{
  "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

FieldTypeRequiredConstraints
namestringYes1 to 50 characters
bash
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.

StatusCause
400Cannot delete your last workspace or Cannot delete the default workspace
403Your role lacks workspace.edit or workspace.delete
404Workspace not found

What can each workspace role do? ​

Roles come from @socifyr/shared. Owner has every permission.

CapabilityOwnerAdminEditorContributor
Create posts and drafts, view postsYesYesYesYes
Publish, archive, unarchive, delete postsYesYesYesNo
Approve and reject postsYesYesYesNo
Upload and view mediaYesYesYesYes
Delete mediaYesYesYesNo
View analyticsYesYesYesYes
Use AI generationYesYesYesYes
View membersYesYesYesYes
Invite, remove, change rolesYesYesNoNo
Create, update, delete, view API keysYesYesNoNo
Edit workspace and webhooksYesYesNoNo
Connect and disconnect accountsYesNoNoNo
Delete workspace, manage billingYesNoNoNo

How do I invite a teammate? ​

POST /workspaces/current/invitations

FieldTypeRequiredConstraints
emailstringYesValid email
roleKeyenumYesADMIN, EDITOR, CONTRIBUTOR. OWNER is not allowed.
bash
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" }'
json
{
  "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:

json
{
  "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.

StatusCause
400The 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
404Membership 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.

Next steps ​