Declare RSC permission requirements for an agent or app

You can use the Teams Developer Portal to declare RSC permission requirements for an agent or app, or manually configure them in the app manifest.

Declaring a permission doesn't grant access: an authorized user grants consent when they install the app in the target resource, subject to your organization's consent policies. The installation dialog shows the permissions requested by the app.

Prerequisites

This article assumes that you already have an agent or app set up through the Teams agent quickstart or a similar process.

Before you declare permissions:

• Identify the RSC permissions and resource scopes required by your app. Request only the permissions that its features need.
• Have the existing application (client) ID available for the app's webApplicationInfo.id property.
• Ensure your organization's policies allow the required consent. Work with your administrator if consent is blocked. For related admin guidance, see Grant and manage consent to Teams app permissions.

For custom app testing, ensure your organization allows custom app uploads and use an app configured for the organization where you install it. For packaging and installation prerequisites, see Upload your app in Teams.

Teams supports a maximum of 16 RSC permissions declarations per agent or app.

Use of delegated RSC permissions requires the use of app manifest v1.12 or later. Strongly consider updating the version of app manifest used by your agent or app if it is using an older version.

Declare RSC permissions in Developer Portal

Use Developer Portal for Teams to edit your app's permission requirements without editing JSON directly.

1. In Developer Portal, select Apps and open your existing app. If you maintain the app package outside Developer Portal, import the package first.
2. Under Configure, select Basic information and verify that Application (client) ID matches the existing application ID for your app.
3. Under Configure, select Permissions.
4. Select the required RSC permissions under Team Permissions, Chat/Meeting permissions, or User Permissions, depending on the resource your app accesses.
5. Save your changes.
6. Review the updated manifest.json in Configure > App package editor. Confirm that the permission names and types match your requirements before using the updated package.

For more information, see Manage your apps in Developer Portal.

Declare RSC permissions in the app manifest

As an alternative to Developer Portal, you can manually edit your agent or app's app manifest directly. Use the format for your app manifest version.

App manifest v1.12 or later

To declare RSC permissions in the app manifest:

1. Add the webApplicationInfo key to your app manifest with the following values:

   Name	Type	Description
   id	String	The existing application (client) ID for your agent or app.
   resource	String	Optional authentication resource value. It doesn't grant RSC access. Preserve the configured value if your app uses single sign-on (SSO).

2. Add permissions needed by your app.

   Name	Type	Description
   authorization	Object	List of permissions that the app needs to function. For more information, see authorization in app manifest.

   List each permission name and its Application or Delegated type in authorization.permissions.resourceSpecific. If an app supports installation in both team and chat scopes, you can declare both team and chat permissions in the same array. Include only the permissions that your app needs; the RSC overview lists the supported permissions.

Example:

{
    "webApplicationInfo": {
        "id": "00000000-0000-0000-0000-000000000000",
        "resource": "https://RscBasedStoreApp"
    },
    "authorization": {
        "permissions": {
            "resourceSpecific": [
                {
                    "name": "TeamSettings.Read.Group",
                    "type": "Application"
                },
                {
                    "name": "ChannelMeetingStage.Write.Group",
                    "type": "Delegated"
                }
            ]
        }
    }
}

App manifest v1.11 or earlier

Add the webApplicationInfo key to your app manifest with the following values:

If an app is meant to support installation in both team and chat scopes, then both team and chat permissions can be specified in the same app manifest under applicationPermissions.

Example:

{
    "webApplicationInfo": {
        "id": "00000000-0000-0000-0000-000000000000",
        "resource": "https://RscBasedStoreApp",
        "applicationPermissions": [
            "TeamSettings.Read.Group",
            "TeamsActivity.Send.User"
        ]
    }
}

Verify the RSC permissions granted to your app

Before you verify grants, install your app in the team, chat, or personal scope you want to test. For custom app installation, see Upload your app in Teams. Have an authorized user consent to the requested permissions.

Verify grants after the first installation, after changing permission requirements and completing the applicable app update and consent flow, or when troubleshooting an access-denied response. This check distinguishes permissions declared in the manifest from permissions actually granted on a specific resource.

For example, if your app requests TeamSettings.Read.Group and is installed in team A, inspect the grants for team A. Find your app's application ID and confirm that its grants include that permission. A grant in team A doesn't grant the same access to team B.

The following steps inspect application RSC permissions through Microsoft Graph. Delegated RSC permissions are used through Teams client APIs in the context of a signed-in user; the application-grant checks below don't verify that delegated behavior.

1. Authorize the verification request.
2. Check the RSC permissions granted to a specific resource.

Authorize the verification request

You can use Microsoft Graph Explorer to inspect grants interactively. Sign in with a work or school account in the organization where the app is installed. Review the Permissions section in the API reference for the resource you're inspecting and authorize the required delegated permission for Graph Explorer.

These permissions authorize the inspection tool to read grants. They aren't the permissions being verified for your app. An authorization error on an inspection request doesn't, by itself, mean your app's RSC grant is missing.

If you send requests from your own tool instead, obtain a Microsoft Graph access token using the appropriate delegated authentication flow or application authentication flow, with the permissions required by that inspection API. You don't need to implement token acquisition in your app just to use Graph Explorer.

Check the RSC permissions granted to a specific resource

Use the procedure for your resource below. The permissionGrants endpoints return grants, not a list of installed apps. To investigate installation separately, use List apps in team, List apps in chat, or List apps for user.

In a successful 200 OK response:

• Find entries whose clientAppId matches webApplicationInfo.id in your app manifest. Don't confuse it with the top-level app manifest id.
• Compare each entry's permission with the application permission names declared for that resource scope.
• Check that permissionType is Application for the application grants you're verifying.

If an expected grant is absent, check the resource ID, the installed app package and its application ID, and whether consent to the updated permissions completed. Work with your administrator if organizational policy prevents consent. Inspecting grants confirms recorded access; it doesn't prove that your app's API calls work. Follow up with Test resource-specific consent permissions in Teams.

Check your app for added RSC permissions in a team

1. In Teams, find the team where you've installed the app.

2. Select More options (...) for that team.

3. Select Get link to team from the dropdown list.

4. Copy the groupId value from the link and use it as {team-id} in the following request.

5. In Graph Explorer, send the request:

   GET https://graph.microsoft.com/v1.0/teams/{team-id}/permissionGrants
   

   Match clientAppId to your app's webApplicationInfo.id and compare the returned permissions with the application permissions requested for the team.

For request permissions and response details, see List permissionGrants of a team.

Check your app for added RSC permissions in a chat

1. Get the ID of the chat where you've installed the app. You can use List chats to find a chat and its id; review that API's permissions before calling it.

2. Replace {chat-id} with the chat ID and send the following request in Graph Explorer:

   GET https://graph.microsoft.com/v1.0/chats/{chat-id}/permissionGrants
   

   Match clientAppId to your app's webApplicationInfo.id and compare the returned permissions with the application permissions requested for the chat.

For request permissions and response details, see List permissionGrants of a chat.

Check your app for added RSC permissions for a user

1. Use Get user to find the ID of the user whose personal scope contains the installed app. Review that API's permissions before calling it.

2. Replace {user-id} with the user ID and send the following request in Graph Explorer:

   GET https://graph.microsoft.com/v1.0/users/{user-id}/permissionGrants
   

   Match clientAppId to your app's webApplicationInfo.id and compare the returned permissions with the application permissions requested for the user.

For request permissions and response details, see List permissionGrants of a user.

Code sample

The two Node.js samples below are Teams tab samples that use the Teams JavaScript client library (@microsoft/teams-js) and the Microsoft Graph client. They aren't Teams SDK samples.

See also

• Test resource-specific consent permissions in Teams
• Resource-specific consent for your Teams app
• Manage your apps in Developer Portal
• Grant and manage consent to Teams app permissions
• List permissionGrants of a user
• Send notification to a user