Platform API
Connect your own platform to your enterprise space with API keys: create users, assign seats, sign the desktop app in and read the monthly report.
If your company or your product already has its own platform and sign-in (for example a customer portal), it can drive your space directly, server to server.
Create an API key
In Integration → API keys, click Create a key, give it a name and choose its permissions:
| Permission | Allows |
|---|---|
users:write | Create or link users, and remove them |
seats:write | Give or remove seats |
sessions:write | Sign the desktop app in, create web sign-in links |
reports:read | Read the monthly report |
The key (vek_…) is shown once: store it in your platform's secrets. Up to 20 active keys. Revoke stops a key immediately.
Call the API
Base URL: https://api.vatoide.com/api/enterprise/v1. Send the key as Authorization: Bearer vek_…. Your users are identified by your identifier (externalUserId), never by a Vato identifier.
curl -X POST https://api.vatoide.com/api/enterprise/v1/users \
-H "Authorization: Bearer $VATO_API_KEY" -H "Content-Type: application/json" \
-d '{"externalUserId":"u-123","email":"jane@acme.com","name":"Jane","seat":"active"}'| Request | Effect |
|---|---|
POST /users | Creates or links the Vato account (seat: active, none, or absent to follow your automatic rules). Optional organizationId: your customer, shown in the report. |
GET /users/{externalUserId} | The linked account and its seat. |
PUT /users/{externalUserId}/seat | {"status":"active"} or {"status":"revoked"}. |
DELETE /users/{externalUserId} | Removes the seat, the team memberships and the link. The Vato account stays with its owner. |
POST /device/complete | {"externalUserId","deviceKey"}: signs in the desktop app that opened your sign-in page. |
POST /login-links | {"externalUserId","redirect"}: a one-time link that signs the person in on vatoide.com (valid 10 minutes). |
GET /report?month=YYYY-MM&format=csv | The month's active users, per organization. |
Sign the desktop app in from your platform
- In Sign-in, turn on Partner platform and enter Your platform's sign-in page (https only).
- When a user clicks Sign in in the app, the app opens your page with
device_keyandcallback_schemeparameters. - After the user signs in on your platform, call
POST /device/completewith their identifier and thedevice_key. Then redirect the browser to<callback_scheme>://auth/callbackto bring the app back to the foreground.
Linking rules
The API follows the same rules as SSO: it only creates or links accounts whose address belongs to a verified domain of your space. Platforms that resell Vato under contract can be declared trusted by the Vato team to link other addresses.