Skip to main content

API key admin scopes

To automate tasks that /api/v1 does not cover (users, settings, exports…), a key can call the back-office services (/api/services/app/{Service}/{Method}, the same API the interface uses) with admin scopes. The key acts as a service account of your account, limited by those scopes.

Outside the stable contract

These routes follow the back-office API and may change with it; they are not part of /api/v1. Use a service account with only the roles the integration needs.

Scopes​

ScopeAllows
admin:*Everything the service account can do
admin:<permission>Only that permission and the ones under it, for example admin:Pages.Administration.Users covers Pages.Administration.Users.Create

Effective permissions are the service account's ∩ the key's scopes. A key without an admin scope gets 403 on /api/services/app/*, and older keys with no scopes never get admin scopes.

Set it up​

Today this is done by API, not from the key form. You need the Grant admin API scopes permission (Pages.Administration.ApiKeys.AdminScopes), with an administrator session.

  1. Create the service account: POST /api/services/app/ApiKey/CreateServiceAccount with name. It is a user with no interactive access: it never signs in (password, external login, impersonation and the rest are refused).
  2. Give it permissions as for any user (roles or permissions) in user management.
  3. Create or edit the key with CreateApiKey or UpdateApiKey, setting scopes (for example "admin:Pages.Administration.Users") and serviceUserId to the service account's id.
curl -s "$BASE/api/services/app/User/GetUsers?MaxResultCount=10" \
  -H "Authorization: Bearer mk_xxxxxxxx"

Security rules​

  • A key with an admin scope needs an active service account of the same account; an ordinary user cannot be bound.
  • You cannot grant an admin:<permission> you do not hold, nor bind a service account that, within the key's scopes, holds a permission you do not (binding the administrator with admin:* requires holding all of its permissions).
  • A call made with the key cannot modify its own service account (permissions, roles, email, password, deletion): 403.
  • It cannot give permissions or roles the caller does not hold, nor change the email or password of a user with more permissions.
  • Only actions that require a named permission are reachable. Personal-use services (profile, account, linked accounts, delegations…) always give 403 with a key, even with admin:*.
  • Every call is written to an audit log (key, service account, path, permissions granted or denied, and status).

You can also get a short-lived token with OAuth2 and ask it for admin:* or an admin:<permission>; the token is bounded the same way.