Skip to main content

How to Expose an API Scope in Microsoft Entra ID

· 12 min read
Jagdish Kumawat
Founder @ Dewiride

A registered API still can't be asked for a token: apps need a name to ask for and a permission to ask with. Both live on the registration's Expose an API page. This guide sets the API's Application ID URI and adds its first scope in the Microsoft Entra admin center, then does the same with the Azure CLI.

What a Scope Is​

A scope is a permission your API defines, such as call this API as the signed-in user. An app that wants to call your API asks Microsoft Entra ID for a token with that scope, and the token lists the scopes it was granted in its scp claim. Your API checks the claim on every request, and does only what the token allows. Scopes of this kind are delegated permissions: the app acts for a signed-in person, never on its own.

The scope's full name joins two things:

PartExampleWhat it is
Application ID URIapi://22222222-2222-2222-2222-222222222222The API's name in tokens. Every token for the API carries it as its audience, the aud claim
Scope nameaccess_as_userThe permission
Full scopeapi://22222222-2222-2222-2222-222222222222/access_as_userWhat an app asks for

The examples on this page expose a scope on a registration called Dewiride Service Desk API. If your API isn't registered yet, start with How to Register a Web API in Microsoft Entra ID.

Prerequisites​

  • Permission to change the API's registration: you're listed under its Owners, or you have a role such as Cloud Application Administrator.
  • For the Azure CLI route: the Azure CLI signed in to the API's tenant (az login).

Step 1: Open Expose an API​

In the Microsoft Entra admin center, browse to Entra ID > App registrations and open your API's registration. Under Manage, select Expose an API. On a new registration, all three parts of the page are empty:

The Expose an API page with an Add link next to Application ID URI highlighted, Scopes defined by this API showing No scopes have been defined, and Authorized client applications showing No client applications have been authorized, with Add a client application dimmed

Add a client application is dimmed: a client app can only be authorized for a scope, and there is none yet.

Step 2: Set the Application ID URI​

Select Add next to Application ID URI. The portal proposes api:// followed by the registration's client ID:

The Edit application ID URI panel explaining that the URI is the prefix for scopes and the value of the audience claim in access tokens, with the value api://22222222-2222-2222-2222-222222222222 and the Save button highlighted

The panel says what the URI is for: it's the prefix for scopes and in access tokens, it is the value of the audience claim. Keep the proposed value and select Save. It's unique by construction, and Microsoft's guide says an Application ID URI must be globally unique. You can choose a readable one instead, such as https://contoso.com/api, but then your API's code must be told to accept it: in an ASP.NET Core API that uses Microsoft.Identity.Web, that's an extra Audience setting the default URI doesn't need.

Step 3: Add a Scope​

Select Add a scope and fill in the panel:

FieldValueWhat it's for
Scope nameaccess_as_userThe permission's name in tokens. No spaces; at most 120 characters
Who can consent?Admins and usersWhether people may agree to it for themselves, or only an administrator, for everyone
Admin consent display nameAccess the Dewiride Service Desk API as a userThe title administrators see when they consent for the whole organization
Admin consent descriptionAllows the app to call the Dewiride Service Desk API on behalf of the signed-in user.The longer text administrators see
User consent display nameAccess the Dewiride Service Desk API as youThe title people see when they consent for themselves
User consent descriptionAllows the app to call the Dewiride Service Desk API on your behalf.The longer text people see
StateEnabledWhether apps can ask for the scope

The Add a scope panel with the scope name access_as_user, the full scope api://22222222-2222-2222-2222-222222222222/access_as_user below it, Who can consent set to Admins and users, the four consent texts filled in, State Enabled and the Add scope button highlighted

Below the name, the panel shows the full scope as you type: api://<client ID>/access_as_user. That is the string apps ask for.

Who can consent? decides who may say yes when an app asks for the scope. Microsoft recommends Admins only for higher-privileged permissions. With Admins and users, people can agree for themselves, if your organization's consent settings allow it; the user consent texts appear only then. access_as_user lets an app do only what the signed-in person could do anyway, so Admins and users fits. The name follows a common convention for an API's main delegated permission; Microsoft's guide also suggests resource.operation.constraint names, such as Employees.Read.All, when an API has several.

Select Add scope. The page now shows the URI and the scope:

The Expose an API page with the Application ID URI api://22222222-2222-2222-2222-222222222222 and one scope, api://22222222-2222-2222-2222-222222222222/access_as_user, that Admins and users can consent to, with its admin and user consent display names starting Access the Dewiride Ser… and the State Enabled

Apps can now ask for the scope. Two things decide whether someone is asked to consent when they do: the app's own registration lists the permission (How to Add an API Permission to an App Registration in Microsoft Entra ID), and the API can trust apps you choose so their users are never asked (How to Pre-Authorize a Client Application for Your API in Microsoft Entra ID).

Do It with the Azure CLI​

The examples below work on a registration called My Web API. First, keep its client ID in a variable:

Terminal
API_APP_ID=$(az ad app list --display-name "My Web API" --query "[0].appId" --output tsv)

Set the Application ID URI​

az ad app update sets it, and prints nothing when it succeeds:

Terminal
az ad app update --id $API_APP_ID --identifier-uris "api://$API_APP_ID"

Add the Scope​

az ad app has no option for scopes, so this step goes to Microsoft Graph, the API behind the admin center, with az rest. A scope needs an ID of its own, a new GUID that you make up. The commands below create one, write the scope into a file named api.json, and send the file:

Terminal
SCOPE_ID=$(uuidgen)
cat > api.json <<EOF
{
"api": {
"oauth2PermissionScopes": [
{
"id": "$SCOPE_ID",
"value": "access_as_user",
"type": "User",
"isEnabled": true,
"adminConsentDisplayName": "Access My Web API as a user",
"adminConsentDescription": "Allows the app to call My Web API on behalf of the signed-in user.",
"userConsentDisplayName": "Access My Web API as you",
"userConsentDescription": "Allows the app to call My Web API on your behalf."
}
]
}
}
EOF
az rest --method PATCH --uri "https://graph.microsoft.com/v1.0/applications(appId='$API_APP_ID')" --body @api.json

az rest prints nothing when the update works. The file's fields are the panel's fields under their Microsoft Graph names:

Field in api.jsonIn the admin center
idNot shown: the scope's own ID, which other apps' registrations refer to
valueScope name
typeWho can consent?: User is Admins and users, Admin is Admins only
isEnabledState
The four …ConsentDisplayName and …ConsentDescription fieldsThe four consent texts

uuidgen prints the GUID in capitals on macOS; Microsoft Graph accepted it and stored it in lowercase. Check the result:

Terminal
az ad app show --id $API_APP_ID --query "{identifierUris:identifierUris, scopes:api.oauth2PermissionScopes[].{id:id, value:value, type:type, isEnabled:isEnabled}}"
Output
{
"identifierUris": [
"api://44444444-4444-4444-4444-444444444444"
],
"scopes": [
{
"id": "66666666-6666-6666-6666-666666666666",
"isEnabled": true,
"type": "User",
"value": "access_as_user"
}
]
}

api.json holds nothing secret; delete it or keep it with your other setup scripts.

Common Mistakes​

MistakeWhat happensDo this instead
Changing the Application ID URI after apps use itApps asking for the old full scope get no token, and the API refuses tokens with the old audienceChoose the URI once. Keep the proposed api://<client ID> unless you need a readable one
Asking for the scope name alone, access_as_userThe request doesn't name your API, so it can't get a token for itAsk for the full scope, api://<client ID>/access_as_user
Admins only on a scope people should consent to themselvesPeople can't agree to it for themselves: an administrator has to consent for the whole organization firstAdmins and users for permissions that only act as the signed-in person
Removing an enabled scope in one stepMicrosoft Graph requires a scope to be disabled before it's removedFirst set isEnabled to false, then remove the scope in a second update. Keep the scope's id whenever you only change its texts

Troubleshooting​

SymptomLikely causeFix
Add a client application is dimmedThe API has no scope yetAdd a scope first
An app gets a token, but the API answers 401The token's audience isn't the Application ID URI your API expectsCheck that the app asks for the full scope, and that the API's settings match the URI
The API answers 403 ForbiddenThe token doesn't carry the scope the API requiresAsk for the exact full scope the API checks for

FAQ​

What's the difference between a scope and an app role?​

A scope is a delegated permission: an app acts for a signed-in person. An app role can also be granted to an application that runs on its own, without anyone signed in. The Expose an API page creates scopes only; app roles have their own page, App roles.

How many scopes should an API have?​

As few as it needs. One scope that lets an app act as the signed-in person suits most APIs used by their own apps. Add more when different apps should be able to do different things.

Only when someone is asked to consent. When an API pre-authorizes an app, its users are never asked, so they never see them.

Conclusion​

The Expose an API page turns a registered API into one apps can ask for. Set the Application ID URI, keeping the proposed api://<client ID>, and add a scope such as access_as_user that Admins and users can consent to. Apps then ask for the full scope, api://<client ID>/access_as_user, and your API checks the token's scp claim. With the Azure CLI, az ad app update sets the URI, and az rest adds the scope through Microsoft Graph.

Additional Resources​