Skip to content
Optiwork API Docs

Prepare to enter a space

POST
/spaces/{space}/joins/setup
curl --request POST \
  --url https://spaces.work.optidata.cloud/api/spaces/a3051110-3152-412d-a015-6d0228be403e/joins/setup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "participant_name": "example" }'

Returns what the Spaces client needs to put the caller inside the space: a short-lived entry token (join_token, valid for 60 seconds), the address of the realtime server (colyseus_url) and of the Spaces client (frontend_url), the world to load, the caller’s name, role and avatar, and what the caller may do there.

Ask for a new setup every time you enter; do not store the token. Archived spaces cannot be entered (403).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
space
required
string

The space’s uuid or hash.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
participant_name

Display name for a guest. Signed-in users always appear under their Optiwork name.

string | null
<= 255 characters
Examplegenerated
{
  "participant_name": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Everything needed to enter the space.

Media typeapplication/json
object
space_id
required
integer
setup_info
required
object
space_uuid
required
string
space_hash
required
string
space_name
string
map

The world to load — a world identifier, or a built-in office.

string
map_source
string
Allowed values: tenant builtin
map_version
integer | null
room_name

The realtime room of the space.

string
colyseus_url
required

Address of the realtime server.

string
join_token
required

Entry token for the realtime server. Valid for 60 seconds.

string
frontend_url
required

Address of the Spaces client.

string
tenant

Your company’s identifier.

string
participant_name
string
participant_role
string
Allowed values: owner member guest
skin

The caller’s avatar.

string
has_skin_preference
boolean
available_skins
Array<string>
is_custom_skin_accepted
boolean
profile_photo_url
string | null
is_super_admin
boolean
is_builder
boolean
can_edit

Whether the caller may edit the world — anywhere for builders, inside their groups’ areas for everyone else.

boolean
group_ids

The ids of the caller’s groups, as used as keys of group_areas.

Array<string>
features
object
chat_enabled
boolean
max_participants_per_space
integer | null
key
additional properties
any
locale
string
Examples
Examplesetup
{
  "space_id": 2,
  "setup_info": {
    "space_uuid": "a3051110-3152-412d-a015-6d0228be403e",
    "space_hash": "a3051110-31f8-4b91-8026-owt42-e19896afc357",
    "map": "a28e5bf3-26b4-4a34-9f98-9a116a2700ca",
    "map_source": "tenant",
    "map_version": 8,
    "room_name": "owt42:a3051110-31f8-4b91-8026-owt42-e19896afc357",
    "colyseus_url": "wss://spaces-mpws.work.optidata.cloud:443",
    "join_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJPcHRpd29yayBTcGFjZXMifQ.c2lnbmF0dXJl",
    "frontend_url": "https://spaces-mp.work.optidata.cloud/?via=link",
    "tenant": "owt42",
    "space_name": "Acme HQ",
    "participant_name": "Ana Souza",
    "participant_role": "owner",
    "skin": "premade:04",
    "has_skin_preference": true,
    "available_skins": [
      "premade:01",
      "premade:02",
      "premade:03",
      "premade:04"
    ],
    "is_custom_skin_accepted": true,
    "profile_photo_url": "https://spaces.work.optidata.cloud/vendor/opticloud/images/user-default.svg",
    "is_super_admin": false,
    "is_builder": true,
    "can_edit": true,
    "group_ids": [],
    "features": {
      "chat_enabled": true,
      "max_participants_per_space": 30
    },
    "locale": "en"
  }
}

401

Section titled “401”

No authentication key was sent.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The space is archived, or belongs to another company.

Media typeapplication/json
object
message
required
string
Examples
Examplearchived
{
  "message": "This space has been archived."
}

404

Section titled “404”

Nothing has this identifier.

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}

419

Section titled “419”

The authentication key is expired or not recognised. Get a fresh one and retry.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Exampleexpired
{
  "error": "JWT passport expired: Passport expired"
}

422

Section titled “422”

The body failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examplegenerated
{
  "message": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}