Scopes
Ask only for the scopes your app needs. Third-party apps show them to the user on the consent screen, with the descriptions below.
The scope schema
Scopes follow one schema:
| Form | Grants |
|---|---|
resource | full access (includes reading) |
resource:read | read-only access |
resource:client | access to what the app created itself; only for app tokens (client credentials) of trusted apps, not for personal access tokens |
In the PHP SDK all scopes are constants on Anikeen\Id\Enums\Scope, e.g. Scope::ORDERS_READ for orders:read.
A shop that sells orders and subscriptions typically asks for:
user:read addresses:read payment-methods:read orders subscriptionsuser (full access) passes every endpoint below except preferences, but the consent screen shows it as full access to the account: prefer the narrow scopes.
Anikeen ID scopes
| Scope | Constant | Description |
|---|---|---|
user | USER | Full access to all user data and resources (create, view, edit, delete). Needed to change the profile. |
user:read | USER_READ | View user information (id, email, name, username) |
addresses | ADDRESSES | Full access to all addresses |
addresses:read | ADDRESSES_READ | View all address information |
billing | BILLING | Full access to all billing settings and invoices |
billing:read | BILLING_READ | View billing information |
billing:client | BILLING_CLIENT | Billing settings and invoices created through this app or token only; marks the app token for charges and the billing limit |
invoices | INVOICES | Full access to all invoices |
invoices:read | INVOICES_READ | View all invoice information |
invoices:client | INVOICES_CLIENT | Invoices created through this app or token only |
orders | ORDERS | Full access to all orders (create, edit, cancel) |
orders:read | ORDERS_READ | View order information |
orders:client | ORDERS_CLIENT | Orders created through this app or token only; app token for app orders |
payment-methods | PAYMENT_METHODS | Full access to all payment methods |
payment-methods:read | PAYMENT_METHODS_READ | View payment method information |
subscriptions | SUBSCRIPTIONS | Full access to all subscriptions (create, edit, cancel) |
subscriptions:read | SUBSCRIPTIONS_READ | View subscription information |
subscriptions:client | SUBSCRIPTIONS_CLIENT | Subscriptions created through this app or token only; app token for app subscriptions and checkout sessions |
transactions | TRANSACTIONS | Full access to all transactions |
transactions:read | TRANSACTIONS_READ | View transaction information |
transactions:client | TRANSACTIONS_CLIENT | Transactions created through this app or token only |
ssh-keys | SSH_KEYS | Full access to all SSH keys |
ssh-keys:read | SSH_KEYS_READ | View SSH key information |
preferences | PREFERENCES | View and change the user's shared preferences, such as the appearance |
preferences:read | PREFERENCES_READ | View the user's shared preferences |
preferences:client | PREFERENCES_CLIENT | Lets a trusted app store preferences of its users in its own namespace, as registered by Anikeen |
Scopes alone don't grant access to app features
Any client can request any scope. Features for trusted apps (charges, the billing limit, preferences of other users, …) are additionally enabled for your app by Anikeen; the :client scope only labels the app token.
Anikeen Console scopes
The Anikeen Console accepts personal access tokens and OAuth tokens (no client credentials) with these scopes for its product and reseller APIs:
| Scope | Constant | Grants |
|---|---|---|
products:read | PRODUCTS_READ | view the products of your teams |
reseller-customers:read | RESELLER_CUSTOMERS_READ | view a reseller team's customers and invitations |
reseller-customers | RESELLER_CUSTOMERS | manage customers: invite, resend, remove logins (includes reading) |
reseller-grants | RESELLER_GRANTS | grant customers access to products and revoke it |
reseller-orders | RESELLER_ORDERS | order products for customers, charged right away without confirmation |
A full reseller scope includes reading. user and * do not open the reseller endpoints: the token has to carry the reseller scope itself.
Product family scopes beta
Each product family of the Console has its own pair of scopes: the full scope reads, changes and orders products of that family, :read only reads them.
| Family | Full scope | Read-only scope |
|---|---|---|
| Servers (with their floating IPs) | console-servers (CONSOLE_SERVERS) | console-servers:read |
| Containers | console-containers (CONSOLE_CONTAINERS) | console-containers:read |
| Domains | console-domains (CONSOLE_DOMAINS) | console-domains:read |
| DNS zones | console-zones (CONSOLE_ZONES) | console-zones:read |
| Web hosting | console-hosting (CONSOLE_HOSTING) | console-hosting:read |
| Load balancers | console-load-balancers (CONSOLE_LOAD_BALANCERS) | console-load-balancers:read |
| Object storage | console-object-storage (CONSOLE_OBJECT_STORAGE) | console-object-storage:read |
A trusted app acting in the Console for its users asks for these scopes in the login (e.g. console-containers); for app tokens the Console accepts only them, not user. Personal access tokens may use them too, or user / products:read.
Scopes per endpoint
Every endpoint called with a token of the user (OAuth login or personal access token) needs a scope. Reads take <resource>:read or <resource>, changes <resource>. * and user pass everywhere in this table except preferences; user:read only reads the user. The :client scopes belong to app tokens and open none of these endpoints.
Personal access tokens can't carry :client scopes. The settings page doesn't offer them, and creating a token with one is refused (422, with an error on the scope). Tokens created earlier with a :client scope keep it, but it opens nothing; create a new token with <resource>:read or <resource> instead.
Rollout
Anikeen ID first logs requests without the scope and still answers them, so we can tell apps that would break; later it refuses them with 403 and {"message": "Invalid scope(s) provided.", "error": "missing_scope", "scopes": [...]} (scopes: any one of them passes). Check that your app asks for the scopes of every endpoint it calls; users have to sign in again to grant new scopes (a refresh keeps the old ones). Profile changes and preferences were enforced from the start.
| Endpoint | Read with (any of) | Change with |
|---|---|---|
GET /v1/user | user:read, user (without: only id) | |
GET /v1/user/socialite-users, POST /v1/user/profile (profile page link) | user:read, user | |
PATCH /v1/user/profile, POST/DELETE /v1/user/profile/avatar | user | |
GET /v1/billing | billing:read, billing | |
POST /v1/billing/charge, POST /v1/billing/portal | billing | |
GET /v1/addresses, /v1/addresses/{id} | addresses:read, addresses | |
POST, PUT, DELETE /v1/addresses… | addresses | |
GET /v1/invoices, /v1/invoices/{id} | invoices:read, invoices, billing:read, billing | |
GET /v1/transactions, /v1/transactions/{id} | transactions:read, transactions | |
GET /v1/orders… (orders, items, shipments, delivery notes) | orders:read, orders | |
POST, PUT, DELETE /v1/orders…, …/checkout, …/revoke, items, POST …/shipments | orders | |
GET /v1/payment-methods, /{id}, /default | payment-methods:read, payment-methods | |
POST, DELETE /v1/payment-methods…, PUT …/{id}/default | payment-methods | |
GET /v1/subscriptions…, GET /v1/checkout-sessions/{id} | subscriptions:read, subscriptions | |
POST, PUT /v1/subscriptions… (checkout, revoke, pause, resume), POST /v1/checkout-sessions… | subscriptions | |
GET /v1/ssh-keys… | ssh-keys:read, ssh-keys | |
POST, PUT, DELETE /v1/ssh-keys… | ssh-keys | |
/v1/preferences/global… | preferences:read, preferences (not user) | preferences (not user) |
App tokens (/v1/client/*, /v1/admin/*) keep their own checks, see trusted apps. Public endpoints (countries, products, orders/preview, avatars) need no token.
Checking scopes in your own API
If your API accepts Anikeen ID tokens, read the scopes from the token's scopes claim (see Access tokens). * stands for all scopes. With the SDK use anikeenTokenCan() or the scope middleware, see API token guard.