# 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.

```bash
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

1. In **Sign-in**, turn on **Partner platform** and enter **Your platform's sign-in page** (https only).
2. When a user clicks **Sign in** in the app, the app opens your page with `device_key` and `callback_scheme` parameters.
3. After the user signs in on your platform, call `POST /device/complete` with their identifier and the `device_key`. Then redirect the browser to `<callback_scheme>://auth/callback` to 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.

## Related pages

- [Single sign-on](single-sign-on.md)
- [Members, rules and settings](members-rules-and-settings.md)

Source: https://vatoide.com/docs/enterprise/platform-api