Skip to main content
Scopes control what your credential can access. Each endpoint requires a specific scope. If your credential doesn’t carry it, the API returns 403 Forbidden. It never returns partial data or silently omits fields. Designing around scopes from the start keeps your integration predictable and limits the blast radius if a token leaks.

Available scopes

Plans

What a credential can do depends on the plan of the Tikk account it belongs to, not on the developer who built the app. Reading and managing your data works on every plan. Pro is for automation: webhooks.
  • Free scopes work on every plan.
  • Pro scopes can be granted on any plan, but only work while the account is on Tikk Pro. Calls from a Free account return 403 with "error": "plan_required". See Errors.
  • Nothing needs to be reconnected or reissued when the plan changes. After an upgrade the same credential works immediately. After a downgrade, Pro calls return plan_required again and webhooks pause.
The API also follows the account’s plan limits: creating a service beyond the Free limit returns the same plan_required error, just like it would be refused in the app. To adapt your UI up front, read plan from GET /profile.

API keys

When you create a key under Settings → API Keys, you choose which scopes it carries. Pick at least one. A key can only call endpoints for the scopes you gave it. You can have up to 10 active keys.

OAuth tokens

When building a partner app, request only the scopes your integration actually needs. You choose your app’s scopes when you register it in the developer portal. Specify them in the scope query parameter on the authorization URL as a space-separated list:
The user sees exactly which scopes your app is requesting on Tikk’s consent screen. The resulting access token only carries the scopes you requested, even if the user’s account has broader permissions.

Missing scope response

If you call an endpoint without the required scope, the API responds with 403 Forbidden and the following body:
scopes lists the scope or scopes the endpoint needs. A credential that holds them but belongs to a Free account gets plan_required instead on Pro endpoints. Check the Errors page for the full list of error codes and their meanings.
Request the minimum scopes your integration needs. Fewer scopes means smaller impact if a token leaks. An attacker with a profile.read-only token can’t reach bookings data or change your services.