A scope is simply a named permission that an application asks for when it talks to Okta.

The plain-English definition

A scope is a short word, such as openid, email, or profile, that describes one slice of access. An application includes a list of these words when it sends a person to Okta to sign in. Each word is a request: “Please let me see this kind of information” or “Please let me do this kind of action.” Okta reads the list, checks its rules, and then either grants the scopes, grants only some of them, or refuses the request.

Scopes exist because of a very old and very sensible security idea called least privilege. Give every person and every program the smallest amount of access that lets them do their job, and nothing more. A calendar widget that only needs to show your name should never be able to read your phone number. A scope is how that limit is written down in a form that computers can check.

Why this matters for everyday people

Every time you press a “Sign in with your company account” button, scopes are working quietly behind the scenes. They decide whether the app learns just that you are a real, signed-in person, or whether it also learns your email address, your department, or your group memberships. Good scope design protects both the person using the app and the company that owns the data.

You cannot understand scopes without knowing the two protocols they live inside.

OAuth 2.0: the permission system

OAuth 2.0 is a standard way for one program to be given limited access to something that belongs to a person, without that person handing over their password. The thing being protected is often called a resource, and the program that guards it is called a resource server. The program that wants access is called the client. The person who owns the data is the resource owner. The trusted referee in the middle is the authorization server, and in this guide that referee is Okta.

When access is approved, the client receives an access token. An access token is like a short-lived wristband at a music festival. It proves you were checked at the gate and tells the staff which areas you may enter. The wristband carries the scopes that were approved.

OpenID Connect: the identity layer

OAuth 2.0 alone answers the question “may this program do something?” It was never designed to answer “who is the person signing in?” OpenID Connect, usually shortened to OIDC, adds that missing piece on top of OAuth 2.0. It introduces the ID token, which is a signed note from Okta saying who the person is, how they signed in, and when.

OIDC also adds a special scope named openid. When a client includes that one word in its request, it is telling Okta, “I am doing a sign-in, so please treat this as an OIDC request and give me an ID token.” Without it, you are doing plain OAuth 2.0 and no identity layer is switched on.

Okta does not have just one referee. It has two kinds, and they treat scopes differently.

The Org Authorization Server

Every Okta organization comes with a built-in authorization server called the Org Authorization Server. Its main job is to sign people into applications using OIDC and to protect Okta’s own management APIs. When you build a plain “sign in with Okta” experience and only need to know who the person is, the Org Authorization Server is often all you need.

A key limit to remember is that the access tokens minted by the Org Authorization Server are meant for Okta’s own APIs, such as the endpoint that returns user information and the management APIs. They are not meant to protect your own custom business APIs. Also, you cannot invent new scopes on it. You choose from a fixed menu that Okta provides.

Custom Authorization Servers

A custom authorization server is one you create and fully control. Okta also gives you one ready-made example called the default authorization server. Here you can define your own scopes, such as a permission to read orders or to approve invoices. You can attach claims, write access policies, set token lifetimes, and decide which clients may request which scopes. This is the right home for protecting your own APIs.

Custom authorization servers are typically part of Okta’s API Access Management capability, so you should confirm that it is included in your organization’s plan before designing around it.

flowchart TD
    A["Application needs tokens"] --> B{"What is the goal?"}
    B -->|"Only sign people in"| C["Org Authorization Server"]
    B -->|"Call Okta management APIs"| C
    B -->|"Protect your own APIs"| D["Custom Authorization Server"]
    C --> E["Fixed built-in scopes"]
    D --> F["Built-in plus your own custom scopes"]
        

The OpenID Connect specification defines a small family of scopes that every compliant provider understands, and Okta supports all of them.

Walking through them one by one

The openid scope is the foundation. Every OIDC request must include it. The ID token you receive always includes a subject value, which is the unique and unchanging identifier of the person inside Okta. Applications should treat that subject value as the true key for the person, because names and email addresses can change.

The profile scope is about how a person is described. The email scope is narrower and answers a very common need: how can I contact this person, and has the address been checked? The address and phone scopes are used less often, and because they touch more sensitive personal information, applications should only ask for them when there is a clear reason.

The offline_access scope behaves differently from the others. It does not reveal any facts about the person. Instead it changes how long the application can keep working, by allowing a refresh token to be issued. We give this scope its own chapter later.

How the standard scopes combine

Scopes are meant to be combined, and the order in which you list them does not matter. A typical web application asks for openid profile email and receives an ID token plus the matching facts. A mobile app that must stay signed in for weeks adds offline_access. A very small application that only needs to know that someone is signed in can ask for openid alone. The golden rule is that each extra word should be justified by a feature someone can point to, such as showing a name in the corner of the screen or sending a receipt to an email address.

It also helps to remember that a scope only opens the door to data that exists. If a person’s profile in Okta has no phone number, asking for the phone scope will not invent one. The claim will simply be missing, and the application should be written to cope gracefully with absent facts instead of assuming every value will arrive.

Beyond the standard family, Okta adds a few scopes of its own for needs that OIDC does not cover.

The groups scope

Many companies organise people into groups such as “Finance”, “Support Agents”, or “Administrators.” Applications often want to know these groups so they can show the right menus. The groups scope is how an application asks for that list. It will only work as expected when the groups claim has been configured, including a filter that says which groups should be included. On a custom authorization server, you create a claim of the groups type and tie it to this scope.

A word of caution: a person might belong to hundreds of groups, and putting all of them into a token can make the token large and slow. A good filter that sends only the groups the application actually cares about is both faster and safer.

The device_sso scope

Imagine a company with several mobile apps from the same family. A person signs into the first app and expects the others to simply recognise them. The device_sso scope supports that experience by returning a device secret that cooperating apps can use to get their own tokens without another full sign-in. It is a specialised tool for native-app single sign-on and is not needed in ordinary web applications.

The okta.* management scopes

These scopes have names beginning with okta. followed by the thing and the action, for example reading users or managing applications. They protect Okta’s own administrative APIs. They are granted to an application by an administrator, never by an ordinary end user clicking an approval button. Because they can change the identity system itself, they should be handed out with great care and always as narrowly as possible.

Beginners often mix these two words up. They are partners, but they are not the same thing.

Two different ideas

A scope is a request for a category of access. A claim is a single fact about the person, delivered inside a token or from the user information endpoint. A scope usually unlocks a bundle of claims. For example, asking for the email scope leads to claims named email and email verified appearing. Asking for profile leads to claims such as name, given name, and family name.

graph LR
    S1["Scope: openid"] --> C1["sub"]
    S2["Scope: profile"] --> C2["name"]
    S2 --> C3["given name"]
    S2 --> C4["family name"]
    S2 --> C5["locale"]
    S3["Scope: email"] --> C6["email"]
    S3 --> C7["email verified"]
    S4["Scope: groups"] --> C8["groups"]
        

Where custom claims fit in

On a custom authorization server you can create your own claims, for example a department or an employee number, and decide when they appear. You can make a claim always appear, or appear only when a particular scope is requested. Tying a claim to a scope is a clean way to make sure sensitive facts are only released when the application has asked for them on purpose.

Follow a single scope from the moment an app asks for it until it appears in a token.

sequenceDiagram
    participant U as User
    participant A as Application
    participant O as Okta
    participant R as Resource API
    A->>O: Authorization request with scopes
    O->>U: Sign in and consent if needed
    U->>O: Approves
    O->>A: Authorization code
    A->>O: Exchange code for tokens
    O->>A: ID token and access token
    A->>R: Call API with access token
    R->>R: Validate token and check scopes
    R->>A: Response
        

What if only some scopes are granted?

Sometimes a person approves part of a request, or a policy allows some of the requested scopes but not others. Applications should never assume that everything they asked for was granted. The token response tells the application which scopes were actually issued, and the access token carries the final list in its scp claim. A well-built application checks that list and quietly turns off features whose scopes are missing, perhaps showing a gentle message that invites the person to grant more access when they want that feature.

This habit makes applications resilient. A profile page that cannot read a phone number can still show the name. A reporting screen that was denied the write scope can still display data in read-only mode.

On a custom authorization server you can invent scopes that describe your own business actions.

What goes into a custom scope

When an administrator creates a custom scope in Okta, they fill in a handful of simple fields. Each one has a purpose, and understanding them prevents many surprises.

Naming scopes well

A good scope name is like a good folder name: you can guess what is inside without opening it. A common convention is to name the thing and then the action, so one scope can mean “read orders” and another can mean “write orders.” Keep them small and focused. Avoid vague names such as “all” or “admin,” because vague names invite overly broad access and are hard to review later.

Creating a scope does not mean anyone can use it. Policies decide who gets which scopes.

Policies and rules

On a custom authorization server, an access policy is a container that is assigned to one or more client applications. Inside the policy live one or more rules, and Okta evaluates them in order, using the first rule that matches. A rule can look at which grant type the client is using, which user or group is signing in, and then decide which scopes are allowed. It can allow any scope, or only a named list of scopes.

Rules also control token lifetimes. You can set how long an access token lives, and how long a refresh token may live or remain unused. Short lifetimes for access tokens are a healthy default, because a stolen token then stops working quickly.

The effect on scopes

If a client asks for a scope that the matching rule does not allow, Okta will refuse the request and respond with an error saying the scope is invalid. This is why a scope can exist on the server yet still fail: the existence of a scope and the permission to use it are two separate things.

Because rules are checked from top to bottom and the first match wins, the order of rules matters a great deal. A common pattern is to place the most specific rule first, for example one that gives an administrators group extra scopes, and to put a broader rule for ordinary people below it. If the order is reversed, the broad rule matches first and the special rule is never reached, which is a classic cause of confusing behaviour. Reviewing rule order whenever a policy changes is a small habit that prevents big surprises.

flowchart TD
    A["Client requests scopes"] --> B{"Policy assigned to this client?"}
    B -->|"No"| X["Request denied"]
    B -->|"Yes"| C{"A rule matches grant type and user?"}
    C -->|"No"| X
    C -->|"Yes"| D{"Scopes allowed by the rule?"}
    D -->|"No"| X
    D -->|"Yes"| E{"Consent required?"}
    E -->|"Yes"| F["Show consent screen"]
    E -->|"No"| G["Issue tokens"]
    F -->|"Approved"| G
    F -->|"Declined"| X
        

Sometimes the person must say yes before a scope is granted. Okta lets you choose when.

Why consent exists

Consent is the moment where the person is shown a clear list of what the application wants and chooses to allow it. It is most valuable when the application belongs to someone other than the company that owns the identity system, such as a partner or a third-party product. In that situation, the person deserves to know what they are sharing.

Implicit versus required

Okta lets you mark each custom scope as implicit or required. An implicit scope is granted with no screen. A required scope shows the display phrase and description on a consent page. For first-party applications that your own company builds and trusts, implicit consent is common because showing approval screens for your own internal tools can be annoying and adds little value. For third-party applications, required consent is usually the safer choice.

Applications can also be configured so that consent behaviour matches how much you trust them. A well-known internal portal might skip consent, while a partner integration always asks.

Remember too that a person who has approved a scope once may later change their mind. Good systems give people a way to review the applications they have approved and to take that approval away. When approval is withdrawn, the application should expect that future token requests may fail and should guide the person back through consent if they still want the feature.

Approved scopes show up in different places depending on which token or endpoint you look at.

Three places to look

After a successful sign-in, an application may hold three different things that relate to scopes. The ID token describes the person. The access token carries the permissions for calling an API. The UserInfo endpoint is a service the app can call, using the access token, to fetch more facts about the person.

The ID token is meant for the client application. The client reads it to learn who just signed in. The access token is meant for the resource server, and the client should treat it as an opaque ticket rather than something to pick apart. The list of approved scopes appears inside the access token, in a claim named scp, and the resource server uses it to decide whether the call is permitted.

Where do the claims appear?

Which claims land directly in the ID token and which must be fetched from the UserInfo endpoint can depend on the type of authorization server, the response type used, and how each claim is configured. On a custom authorization server you can configure a claim to be included in the ID token always, or only when no access token is requested. Because details like this can vary with configuration and may change over time, always confirm the current behaviour in Okta’s official documentation when you design a production system.

Access tokens are short-lived on purpose. Refresh tokens let apps keep working without constant sign-ins.

The problem refresh tokens solve

For safety, access tokens usually last only a short time, perhaps an hour or less. That is wonderful for security but would be terrible for convenience if the person had to sign in again each time a token expired. A refresh token solves this. It is a longer-lived credential that the application can quietly present to Okta to receive a brand-new access token.

What you must configure

To receive a refresh token, several things must line up. The application must request the offline_access scope. The application must be allowed to use the refresh token grant type. And, on a custom authorization server, the policy rule must permit the refresh token grant and the scope itself. If any one of these is missing, no refresh token will arrive, which is a very common source of confusion.

Not every request involves a person. Backend services also need scopes.

The client credentials flow

Sometimes there is no human at all. A nightly report job might need to call an internal API, or a provisioning tool might need to read user records from Okta. In these cases the application proves its own identity to Okta and receives an access token that represents the application itself, not any person. This pattern is called the client credentials flow.

Because no person is present, there is no sign-in, no ID token, and no consent screen. The openid scope is not used. What matters entirely is which custom scopes or Okta API scopes the application is allowed to request, and the policy that governs them.

Calling Okta’s management APIs

When a service needs to call Okta’s own APIs, it uses the okta-prefixed scopes from the Org Authorization Server. An administrator must explicitly grant each scope to the application. Okta also expects strong proof of the application’s identity, usually using a signed assertion built from a private key that only the application holds, rather than a simple shared password. In addition, the service is generally assigned an administrative role that limits what it can do, so scopes and roles work together as two locks on the same door.

sequenceDiagram
    participant S as Backend Service
    participant O as Okta
    participant R as Protected API
    S->>O: Prove identity and request scopes
    O->>O: Check policy and allowed scopes
    O->>S: Access token with scp claim
    S->>R: Call API with token
    R->>R: Verify signature, audience, scopes
    R->>S: Data
        

Scopes are a security tool, but only when they are designed and checked with care.

Principles to live by

The first principle is least privilege: every client receives only the scopes it needs today. The second is short lifetimes: access tokens expire quickly, so leaks do limited harm. The third is verification: a resource server must never trust a token blindly. It must check the signature, the issuer, the audience, the expiry time, and the scopes before it allows any action.

The fourth principle is that scopes are not a replacement for authorization inside your own system. A scope says the application is permitted to ask for a category of access. It does not say that this particular person is permitted to see this particular record. Your API still needs to check that the signed-in person owns or may view the data in question.

Thinking about lifetimes and revocation

Every token should answer the question “how long is it good for?” Access tokens work best when they live for minutes or an hour, because the shorter the life, the smaller the window an attacker has. Refresh tokens live longer, so they deserve extra protection and the option to be revoked. When an employee leaves or a device is lost, an administrator should be able to cut off the refresh tokens so that no new access tokens can be created, and the old access tokens simply fade away as they expire.

For very sensitive actions, such as moving money or changing security settings, teams often ask the person to sign in again or to complete another verification step, even if they already hold a valid token. Scopes alone do not provide this. It is an additional safeguard built into the sign-in policy and the application design.

Protecting personal information

Tokens travel through browsers, logs, and networks. Keep sensitive personal data out of access tokens, because they are often passed around and can end up in places you did not intend. Release sensitive facts through scopes that need consent, and prefer fetching them from UserInfo over embedding them everywhere.

When a scope does not behave as expected, a calm, step-by-step investigation almost always finds the cause.

Where to look first

Okta keeps a System Log that records authentication and token activity, including failed requests. When a scope problem appears, the System Log should be your first stop because it shows which client asked, which policy matched, and why a request was refused. Good teams also watch trends: a sudden rise in refused scope requests can mean a mistaken deployment or an attempt to ask for more than a client should have.

The most common problems

A calm checklist

Experienced teams repeat a few good habits and avoid a few tempting mistakes.

Patterns that work

Anti-patterns to avoid

Here are five everyday situations showing how scope decisions look in practice.

You will also notice that none of these scenarios uses a magic setting. They all use the same small toolkit described in this guide: pick the correct authorization server, list the scopes honestly, let policies and consent act as gatekeepers, and let the resource server verify every token. The differences between a small intranet and a large partner platform are mostly a matter of how many scopes there are and how carefully each one is reviewed.

Here is a gentle, repeatable way to plan scopes before you touch a single setting.

flowchart LR
    A["List capabilities"] --> B["Group into scopes"]
    B --> C["Map clients to scopes"]
    C --> D["Set consent rules"]
    D --> E["Write policies"]
    E --> F["Enforce in the API"]
    F --> G["Monitor and review"]
    G --> B
        

Quick answers to questions that beginners ask again and again.

Yes, if you want an OIDC sign-in and an ID token. Without it you are performing a plain OAuth 2.0 request, which gives you an access token but no identity information. The only common exception is a machine-to-machine request, where no person signs in at all.

The most frequent reasons are a misspelled scope, a scope that does not exist on the chosen authorization server, or a policy rule that does not allow that scope for this client. Check the spelling first, then the authorization server, then the rule.

No. Custom scopes belong on a custom authorization server. The Org Authorization Server offers a fixed set of built-in scopes.

A scope is a request for a category of access. A claim is an individual fact delivered in a token or from UserInfo. Approving a scope usually releases a group of claims.

Make sure the application asks for offline_access, that the application is permitted to use the refresh token grant, and that the policy rule on a custom server allows both the grant and the scope.

In the access token, inside the scp claim. The resource server reads this claim to decide whether to allow each call. Client applications should avoid depending on the internal structure of the access token.

No. It delivers the person’s group memberships as a claim. Your application can interpret groups as roles if you design it that way, but Okta treats it as a list of groups, and you remain responsible for deciding what each group means.

No. The scope tells you the application was permitted to ask for a category of access. Your API must also confirm the token is valid and meant for it, and must still check that this person is allowed to reach the specific data requested.

Require it for sensitive scopes and for applications that you do not own or fully control. For your own trusted internal applications, implicit consent usually gives a smoother experience without reducing safety in a meaningful way.

There is no magic number. Aim for scopes that are small enough to be meaningful and large enough to be manageable. If reviewers cannot remember what each scope does, or if you have dozens that are nearly identical, it is time to simplify.

OIDC scopes in Okta are the clear, written permission slips that let applications ask for exactly the access they need. The standard scopes openid, profile, email, address, phone, and offline_access cover identity and session needs. Okta adds groups, device_sso, and the management family for specialised jobs. Custom authorization servers let you design your own scopes for your own APIs, while policies, rules, and consent settings decide who may receive them. Tokens then carry the approved result to the places that need it.

The craft lies in discipline: request little, grant little, verify everything, and keep the story simple enough that a newcomer can read it. If you remember the hotel key card from the beginning of this guide, you already hold the heart of the subject: a good key opens exactly the doors it should and no others.