API Scopes vs Product Entitlements
Separate what a key is permitted to request from what an account’s plan enables, and enforce both checks consistently on each data operation.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
An API key can carry permissions while the account carries product entitlements. A request should satisfy both. A broad key does not automatically unlock an unavailable or unpurchased capability.
Model independent decisions
Authentication identifies the credential and account. Scope authorisation limits operations or resources. Entitlements describe enabled products, quotas or contracted access. Keep expiry, revocation and budget checks separate as needed. The server must enforce these rules; hiding a button in the console is only a user-interface choice.
Worked example: key allows reads, plan excludes product
A key permits read operations for project P. The account is entitled to wallet history but not a particular export product. A request for that export is denied by the entitlement check even though the key is authentic and read-scoped. Conversely, a plan upgrade should not override a deliberately narrow key scope.
Test changes over time
Include plan changes, revoked keys, project mismatch and a cached entitlement that has expired. Return stable documented error semantics without exposing internal account details. A connection test can report eligible capabilities, but every actual operation still needs current checks. Do not rely on a capability list fetched once at login forever.
A practical acceptance test
Test all combinations of valid credential, allowed scope and enabled product. A plan upgrade should not override a read-only or project-restricted key. Revoking the key must deny the operation even if a cached capability list still shows the product. Error responses should distinguish supported public semantics without leaking unrelated account configuration.
Questions about the topic
Frequently asked questions
Does one key need to be created for every product?
Not necessarily. One key can use multiple entitled products under its scopes.
Can a plan upgrade override a restricted key?
It should not silently broaden the key’s deliberately limited permissions.
Standards & technical documentation
