Skip to content

API integration guides

Check permissions before you enable a feature

Read the granted scopes from each token response and enable only the features that those scopes allow.

Run these steps after every login. The issued grant can lack a scope that the client configures. For the grant model, see App permissions.

Prerequisites

  • A token response from a completed login.
  • A list of the scope that each feature of your app needs, from the scope reference.

Warning: Never show a requested scope as granted. Only the token response shows the grant.

Steps

  1. Read the scope field of the token response.
  2. If the field lists the scope of a feature, enable that feature.
  3. If the field does not list the scope, disable the feature.
  4. Show the user which permission the disabled feature needs.
  5. If the response has no scope field, read the validated grant information of your OpenID Connect (OIDC) library.
  6. If an API call returns 403 insufficient_scope, disable the affected feature.
  7. Check the scope selection of the client in the developer portal.
  8. After the client configuration changes, start another login.
  9. Read the scope field of the fresh token response.

Result

Your app enables a feature only when the token grants its scope. The account, unrelated features, and drafts stay available while a permission is missing.

Release checks

These cases test the permission handling of your app before release:

  • The user cancels consent.
  • The token response omits a scope that the client configures.
  • An API call returns insufficient_scope.
  • A token expires while the user moves between pages.
  • The user logs out of your app, then logs in with a different account.
  • Each control works with a keyboard, with touch, and with a screen reader.