Umovi integration platform
OAuth client credentials
REST integrations use OAuth2 client_credentials. They represent an external system acting for one provider, not an end user.
Token request
POST /integrations/oauth/token
Content-Type: application/json{
"client_id": "umovi_voicebot_abc123",
"client_secret": "secret-visible-once",
"grant_type": "client_credentials",
"scope": "catalog:read slots:read reservations:create"
}scope is optional. When supplied, it requests a subset of the scopes assigned to the client; it cannot elevate the client beyond its configured permissions.
Token lifecycle
The response contains access_token, token_type: "Bearer", expires_in: 1800 and the granted space-separated scope. There is no refresh token in this flow; request a new access token with client credentials before expiry. If scope is omitted, the token receives the client’s currently allowed scopes. Unknown or unassigned scopes return 400 with error: "invalid_scope".
Resource access also requires an active integration client, an active provider and a plan with Integration API access. Removing a client scope takes effect for existing tokens too; adding a scope requires a newly issued token.
Scopes
| Scope | Allows |
|---|---|
catalog:read | Read and search catalog data, employees and service/employee resolution. |
services:internal:use | Include provider-internal services when combined with the relevant catalog, slot or reservation scope. |
clients:identify | Recognize an exact caller phone number without returning contact or profile data. |
clients:read | Search provider client records. |
clients:create | Create provider client records. |
clients:update | Update provider client records. |
clients:delete | Delete provider client records. |
slots:read | Search slots and first availability. |
reservations:read | List and read reservations. |
reservations:history:read | Read reservation lifecycle events. |
reservations:create | Create reservations. |
reservations:update | Update reservation details. |
reservations:reschedule | Reschedule according to client-side provider policy. |
reservations:cancel | Cancel reservations. |
webhooks:read | List integration-owned webhooks and delivery attempts. |
webhooks:write | Create, update and delete integration-owned webhooks. |
webhooks:secret:rotate | Rotate webhook signing secrets. |
webhooks:test | Enqueue test webhook deliveries. |
Secret handling
- Keep
client_secretin a server-side secret manager, never in browser or mobile application code. - Do not log token requests, secrets or access tokens.
- Request only the scopes needed by the integration.
- Rotate or revoke a client after suspected exposure.
- Treat provider mismatch and insufficient scope as authorization failures, not retryable transport errors.
The documentation tester keeps credentials and access tokens only in page memory. It clears the client secret after a successful token request. Reloading the page requires authentication again; changing the API origin clears credentials and request/response state. Tokens are not stored in sessionStorage or localStorage.
Providers with a hidden public profile
An active provider may hide their public profile and stop new bookings through
Umovi client apps and the public MCP server. This does not disable an authorised
REST integration: catalog, availability and reservation operations continue to
use the integration's existing scopes. Internal-only services still require
services:internal:use in addition to the operation scope.
Suspended, disabled or archived providers remain subject to the existing access restrictions. Hiding a public profile does not reactivate a provider account.