Frictionless app development and enablement with the Microsoft Teams App Submission API

Office Add-ins team

Note: This blog post has been updated as of March 25, 2021 to reflect General Availability (GA) of this set of APIs.

Microsoft Teams is an emerging canvas for in-house custom apps. Bringing line-of-business apps into chats, channels, and personal scopes in Teams is the most efficient way to link productivity workflows directly to your organization’s conversational platform.

Thousands of organizations have developed custom Teams apps using a variety of development platforms: PowerApps, the SharePoint Framework, and native web apps build on any programming language, to name a few.

But building these apps is just the start. To unlock their potential, users across the organization need a way to discover them in Teams. So, to securely enable apps, an IT department must be involved in the process. Until now, there was nothing connecting these pieces together.

We are excited to announce that the Teams app staging and submission APIs are now generally available on the Microsoft Graph v1.0 endpoint for developers to utilize today. These APIs allow developers to build on the platform of their choice and submit their apps into Teams with zero friction, and helps relieve the burden of discovering, approving, packaging, and deploying by IT.

Custom app lifecycle illustration

What is the Teams App Submission API?

This API is a new entry point, built on Microsoft Graph, that allows organizations to build a proper submission-to-approval pipeline for custom apps on Teams. Because it’s built on Graph, the API is flexible enough to plug into any existing process your organization uses to manage app lifecycles.

App Submission API visual workflow illustration

The API will allow developers full CRUD operations for their submission requests. This means they can submit custom apps, retrieve the status of these submissions, and update/upgrade their apps over time.

App publishing function within Visual Studio Code extension for Teams

Similarly, on the IT side of the fence, the approval of each submission is governed by Graph. This means approval or rejection of any given submission can be automated as well as controlled in the Teams Admin Center.

Screen of Teams Admin Center where IT admins can view pending app submissions

Screen of Teams Admin Center where IT admins can publish or reject submitted apps

Another advantage of building this API on Graph is that Microsoft will soon offer a plethora of upstream callers that use it. This way, organizations can be sure that the submission process is centralized regardless of where apps are being built or which processes developers and IT admins must follow to publish them. Initially, App Studio, Visual Studio, and Visual Studio Code will all use the API. Going forward partner platforms on M365, including Power Apps, and Power Virtual Agents will leverage this API as well.

How should developers use it?

If you’re developing Teams apps using one of our supported IDE extensions such as the Teams extension for Visual Studio and Visual Studio Code, you’ll see a new experience for submitting your app to your organization. The same applies if you’re leveraging one of our supported M365 platforms like Power Apps or Power Virtual Agents.

If you choose to develop Teams apps elsewhere, you can use the Graph API to submit your app.

These same front end surfaces, as well as the Graph API, can be used to retrieve status of your submission, cancel pending submission requests, or submit updates to an existing app (if you’re using the Graph API, make sure the updated app’s ID matches the previous version of the app in the Teams manifest file).

We’re excited to share with you the set of staging and submission APIs now available to you on the Microsoft Graph v1.0 endpoint below:

Stage / publish an app to the catalog Publish an app to the Microsoft Teams apps catalog. POST appsCatalog/teamsApps

Update an app in the catalog Update an app previously published to the Microsoft Teams app catalog. POST appCatalogs/teamsApps{appId}/appDefinitions  

List Teams apps in catalog List the apps published in the Microsoft Teams app catalog, including apps from the Microsoft Teams store, as well as apps from your organization’s app catalog (the tenant app catalog). GET /appCatalogs/teamsApps

Get the bot associated with a specific definition of the Teams app. You can list all the apps in the catalog that contain bots, list all the bots installed in the scope of a team/user/chat/meeting, detect the same bot being shared across multiple apps, and more. GET /appCatalogs/teamsApps/{app-id}/appDefinitions/{app-definition-id}/bot

Delete Teams app Delete an app from an organization’s app catalog (the tenant app catalog). DELETE /appCatalogs/teamsApps/{id}

Get an app in the catalog Get the app in the catalog by mentioning the app ID. GET /appCatalogs/teamsApps({teams-app-id})

List all app definitions for an app  List all app definitions for an app. GET /appCatalogs/teamsApps({teams-app-id})/appDefinitions

Get an app definition for an app Get the app definition for a particular app. GET /appCatalogs/teamsApps({teams-app-id})/appDefinitions({appDefinitionId})

Review and update the publishing state of an app definition. Review and update the publishing state of a staged app definition. An admin can use this API to approve or reject a staged app. PATCHappcatalogs/teamsapps({appId}/appdefinitions/({appDefinitionId})

Of course, if you’re new to developing apps for Teams, check out our resources on Teams app development at the Microsoft Teams Dev Center.

How should IT use it?

This API turns the Teams custom app process for IT on its head. Previously, custom app deployment in Teams was a “pull” model. IT was responsible for discovering, packaging, ingesting, and deploying relevant in-house workflows as Teams apps.

Now, instead of burdening IT for this, the Submission API turns this into a “push” model.

In-house developers and makers anywhere in M365 can decide to package and push their apps to Teams with the click of a button. IT no longer has to package apps manually, they can simply log in to the Teams Admin Portal‘s “Manage Apps” page and find submitted apps there, alongside the list of globally available Teams apps.

Each submission comes with the identity of the user who submitted it. So, in addition to reviewing the app in the admin center, the admin can reach out to this user to further communication.

Finally, approving a submission is a one-click operation. After that, the app is fully deployed, discoverable by end users, and manageable by permission and setup policies.

The approval/rejection operation is available over the Graph API, so this entire end-to-end process can be automated according to your organization’s specific requirements.

Tell us what you think

We welcome your feedback. If you have further questions, you can reach out to us on Microsoft Q&A or StackOverflow.

Happy coding!

Joey Glocke, Senior Program Manager, Microsoft Teams


Feedback usabilla icon