Workspace

The Workspace endpoints control who has access to a smenso workspace. You can invite members and guests, provision members ahead of their activation, and read back the list of all members and guests.

Prerequisites (Getting Started)

This guide assumes you're familiar with:

• Authentication: https://developers.smenso.de/docs/authentication
• Permissions & privacy: https://developers.smenso.de/docs/permissions-privacy

⚠️

Admin permissions required

All write requests of the Integration API require admin permissions. Use the API token of a workspace admin for the invite and provision endpoints.

Available Endpoints

Integration JSON API

Roles

The role field sets the permission level of the invited user.

📘

Admins cannot be guests. Use the member endpoint to invite an admin.

Invite Members

Sends an invitation to each listed email address.

POST /api/integration/workspace/invite/members/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "invites": [
    {
      "email": "[email protected]",
      "role": "member",
      "locale": "en",
      "flags": ["sc-access-hr"]
    },
    {
      "email": "[email protected]",
      "role": "read-only-member"
    }
  ]
}

Invite Guests

Works like inviting members, but with the guest roles and without flags.

POST /api/integration/workspace/invite/guests/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "invites": [
    {
      "email": "[email protected]",
      "role": "restricted-guest",
      "locale": "en"
    }
  ]
}

Provision Members

Provisioning registers members in the workspace without sending an invitation. The email address is used later, once the member is switched from provisioned to active.

POST /api/integration/workspace/provision/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "invites": [
    {
      "email": "[email protected]",
      "firstName": "Max",
      "lastName": "Mustermann"
    }
  ]
}

Response of the Invite and Provision Endpoints

All three write endpoints return the same result object. Every entry of invites is processed independently, so a request can partially succeed.

{
  "hasErrors": true,
  "invited": ["[email protected]"],
  "notInvited": [],
  "errorDetails": ["[email protected]"]
}

⚠️

Check the result, not only the status code. Because entries are processed independently, always evaluate hasErrors, notInvited, and errorDetails to find out which addresses did not go through.

Get Members and Guests

Returns the ID, name, email address, and role of all members and guests of the workspace.

curl --request GET \
     --url https://customersubdomain.smenso.cloud/skyisland/api/integration/workspace/member/json \
     --header 'Authorization: Basic xxxx' \
     --header 'accept: application/json'

[
  {
    "id": "12345678-aa12-3d4f-ab5e-ad6e78dffbc9",
    "name": "Jane Doe",
    "email": "[email protected]",
    "role": "member",
    "isGuest": false
  }
]

Licenses

The number of users you can invite is limited by the licenses available in your workspace. Licenses are managed in the Admin Center.

FAQ

Why do I get a 403 response?

The Integration API write endpoints require admin permissions. Use the API token of a workspace admin.

What is the difference between inviting and provisioning a member?

Inviting sends an invitation email right away. Provisioning only registers the member and sends nothing; the member becomes active once an admin assigns a regular role in the Admin Center.

Can I invite an admin as a guest?

No. Admins cannot be guests. Invite them as members with the role admin.