Inbound API
The inbound API is an HTTP REST API that developers can use to access / modify data stored in the WorkAdventure server.
Members and visitors (self-registered accounts) can both be read and deleted through the
Inbound API, and the type field (member or visitor) tells them apart. Only members can be created or updated.
The list endpoint returns members by default: pass ?type=visitors or ?type=all to include visitors.
Authentication
In order to connect to the inbound API, you will need an authentication token and a premium access to the world.
You can issue a new authentication token in the administration dashboard of WorkAdventure.
- Go to Developers > API keys / Zapier
- In the "API Tokens" section, click on "Create a new token".
- Give your token a name
- Save the token for the next step.
Connecting to the REST API
The API entrypoint is:
https://admin.workadventu.re/api/v1/worlds/[your world slug]
The "world slug" is the last part of the World URL.
On the "edit your world" popup, you can see the "WorkAdventure URL" of your World.
If the "WorkAdventure URL" of your World is https://play.workadventu.re/@/foo/bar, then your "world slug"
is bar.
In order to authenticate with the API, you will need to put the HTTP Authorization header with every request
you make to the API.
The Authorization header MUST be set to the authentication token that you previously generated,
as is (without any "Bearer " prefix).
Webhooks
The API also manages the webhooks of your world, so that your integration can subscribe to events itself (the "REST hooks" pattern), as the Zapier and n8n triggers do:
POST https://admin.workadventu.re/api/v1/worlds/[your world slug]/webhooks
{"url": "https://example.com/workadventure-webhook", "events": ["recording", "visitor"]}
The response contains the webhook's id and the secret that signs its deliveries. This is the only time the secret
is returned, so store it. GET …/webhooks lists the webhooks, GET …/webhooks/{id} returns one, and
DELETE …/webhooks/{id} unsubscribes. They are the same webhooks as in Developers > Webhook settings, where you can
also see their deliveries. A world can have up to 100 webhooks.
Check enabled when your integration starts: WorkAdventure switches a webhook off after repeated failed deliveries,
and a webhook that is switched off receives nothing. Delete it and create a new one.
Complete specs
All the available entry points are exposed in the OpenAPI spec accessible below: