Scopes#

Scopes are string identifiers representing permission sets a client may request. In Curity, a non‑prefix scope can also group claims; if all claims are granted the scope label is added to the token. Prefix scopes are a special form that never contain claims and carry a dynamic suffix for instance‑specific authorization.

Defining scopes in the profile#

When adding a scope decide:

1. Name (keep domain+action concise: accounts_read, invoices_write).
2. Which claims (if any) it should imply.
3. Lifetime (optional TTL shorter than the delegation lifetime).
4. Required? (must be requested; appears locked in consent UI).
5. Prefix or regular?

Avoid excessive scope proliferation; if you need per‑object authorization prefer a prefix scope rather than dozens of static scopes.

Scopes must be configured in the Authorization Server profile before clients can request them.

Assigning scopes to clients#

A client configuration lists the scopes it is allowed to request. Requesting a scope also requests its associated claims. Removing a scope from the client forbids requesting its claims via that scope; individual claims might still be requested if allowed through other scopes (see the Claims page).

Scope lifetimes and refresh behavior#

Each delegation has an overall lifetime. A scope can optionally define its own TTL; after it expires the scope (and its claims) are dropped from subsequently refreshed access tokens while longer‑lived scopes remain.

Example: Banking application#

Scopes:

• account_transfer - high-risk operations (TTL 30m)
• account_balance - low-risk read access (TTL 1 month)

During the first 30 minutes both scopes are present. After 30 minutes refreshes only include account_balance.

Minimum access token TTL safeguard#

To avoid issuing ultra‑short tokens just before a scope expiry, configure min-access-token-ttl. If remaining lifetime for a scope is less than this minimum when refreshing, the server omits that scope and issues a full‑length token with the remaining scopes.

Parameters considered when refreshing:

1. Elapsed time since original issuance.
2. Standard access token lifetime setting.
3. Minimum access token TTL setting.

This may result in tokens with a shorter absolute lifetime than the configured access token lifetime when approaching a scope boundary, but still respecting the minimum.

Given the following example settings:

• Access token lifetime setting = 15 minutes
• Minimum access token time to live = 2 minutes

We can derive the following graph:

As the figure above illustrates, the account_transfer scope was dropped even though 30 minutes had not elapsed since the original issuance. This is because the server won’t issue tokens with a lifetime of less than 2 minutes, in this case, and thus dropping the scope to issue a full length token (15 minutes) according to the configuration.

On the other hand, if the request for a refresh would come after 20 minutes of original issuance, then the server would issue a token, but it would be shorter than the configured access token lifetime. It would be calculated to then max length until next scope must be dropped. In this case that is 10 minutes (T+30 - T+20 = 10). Which still is greater than the minimum access token lifetime setting of 2 minutes. This is illustrated below.

Required scopes#

Marking a scope as required means that it is required to be included in all tokens. If a client does not include a required scope in its request for a new token, the request will be rejected.

Also, in case User Consent is enabled, a required scope will manifest itself as non-deselectable in the User Consent form.

In general, a required scope must be requested by clients, and it will always be bound to tokens issued through the Token Service’s profile.

Prefix scopes#

Prefix scopes are scopes which may contain extra information attached to them. They can be useful for cases in which the access being granted by the scope should be limited to a single instance of a class of actions.

For example, a banking application may need to request permission to complete payment of a specific transaction, rather than for any transactions at all.

In this case, a prefix scope called payment_transaction: could be defined, where the ID of the particular transaction for which the grant is being given is expected to be attached to the scope itself, tying the scope permission to a particular transaction instance, rather than to just any transaction in general.

The following table demonstrates the relation between a configured prefix scope, and examples of valid scopes a client may request:

Once a prefix scope is issued with a token, its value cannot changed by refreshing the access token. The scope may be “dropped” from refreshed access tokens by simply not requesting it during refresh, but because the scope was granted with the initial delegation, the client may, at any time in the future, request the scope again with the same initial value (but not with a different suffix, even if the prefix is still the same).

Customization and localization#

User consent templates ( User Consent ) can show prefix scopes with tailored messages. Provide localized descriptions via localization and see Showing prefix scopes for template adjustments.

Scopes and claims relationship#

Requesting a regular scope implies requesting its claims. If all claims are granted the scope label is added to the token. If any claim is withheld the scope label is dropped while still returning granted claims. For requesting individual claims or advanced claim resolution, see the Claims page.

Design guidance#