Publish teamsApp

Article
02/14/2024

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Publish an app to the Microsoft Teams app catalog. Specifically, this API publishes the app to your organization's catalog (the tenant app catalog); the created resource has a distributionMethod property value of organization.

The requiresReview property allows any user to submit an app for review by an administrator. Admins can approve or reject these apps via this API or the Microsoft Teams admin center.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	❌

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission Type	Permissions (from least to most privileged)
Delegated (work or school account)	AppCatalog.Submit, AppCatalog.ReadWrite.All, Directory.ReadWrite.All**
Delegated (personal Microsoft account)	Not supported.
Application	Not supported.

Note: Permissions marked with ** are supported only for backward compatibility. We recommend that you update your solutions to use an alternative permission listed in the previous table and avoid using these permissions going forward.

HTTP request

POST /appCatalogs/teamsApps

To publish an app that requires a review:

POST /appCatalogs/teamsApps?requiresReview={Boolean}

Query parameters

Property	Type	Description
requiresReview	Boolean	This optional query parameter triggers the app review process. Users with admin privileges can submit apps without triggering a review. If users want to request a review before publishing, they must set requiresReview to `true`. A user who has admin privileges can opt not to set requiresReview or set the value to `false` and the app will be considered approved and will publish instantly.

Request headers

Header	Value
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type	application/zip. Required.

Request body

In the request body, include a Teams zip manifest payload. For details, see Create an app package.

Each app in the app catalog must have a unique manifest ID.

Response

If successful, this method returns a 200 OK response code and a teamsApp object. If the app manifest has any validation errors, the request returns an error response with details about the schema errors.

Examples

Example 1: Publish an app to the app catalog

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/appCatalogs/teamsApps
Content-type: application/zip

[Zip file containing a Teams app package]

Snippet not available

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta app-catalogs teams-apps create

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const teamsApp = [Zip file containing a Teams app package];

await client.api('/appCatalogs/teamsApps')
	.version('beta')
	.post(teamsApp);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Teams

$params = [Zip file containing a Teams app package]


New-MgBetaAppCatalogTeamApp -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

For information about how to create a Microsoft Teams application zip file, see Create an app package.

Response

The following example shows the response.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "e3e29acb-8c79-412b-b746-e6c39ff4cd22",
  "externalId": "b5561ec9-8cab-4aa3-8aa2-d8d7172e4311",
  "displayName": "Test App",
  "distributionMethod": "organization"
}

Example 2: Upload a new application for review to an organization's app catalog

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/appCatalogs/teamsApps?requiresReview=true
Content-type: application/zip


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.AppCatalogs.TeamsApps.PostAsTeamsAppsPostResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.RequiresReview = "true";
});

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta app-catalogs teams-apps create

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphappcatalogs "github.com/microsoftgraph/msgraph-beta-sdk-go/appcatalogs"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestRequiresReview := "true"

requestParameters := &graphappcatalogs.AppCatalogsTeamsAppsRequestBuilderPostQueryParameters{
	RequiresReview: &requestRequiresReview,
}
configuration := &graphappcatalogs.AppCatalogsTeamsAppsRequestBuilderPostRequestConfiguration{
	QueryParameters: requestParameters,
}

graphClient.AppCatalogs().TeamsApps().PostAsTeamsAppsPostResponse(context.Background(), configuration)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.appCatalogs().teamsApps().post(requestConfiguration -> {
	requestConfiguration.queryParameters.requiresReview = "true";
});

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/appCatalogs/teamsApps?requiresReview=true')
	.version('beta')
	.post();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\AppCatalogs\TeamsApps\TeamsAppsRequestBuilderPostRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new TeamsAppsRequestBuilderPostRequestConfiguration();
$queryParameters = TeamsAppsRequestBuilderPostRequestConfiguration::createQueryParameters();
$queryParameters->requiresReview = "true";
$requestConfiguration->queryParameters = $queryParameters;


$graphServiceClient->appCatalogs()->teamsApps()->post($requestConfiguration)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Teams

New-MgBetaAppCatalogTeamApp -Requiresreview true

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


from msgraph import GraphServiceClient
from msgraph.generated.appCatalogs.teamsApps.teams_apps_request_builder import TeamsAppsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = TeamsAppsRequestBuilder.TeamsAppsRequestBuilderPostQueryParameters(
		requires_review = "true",
)

request_configuration = TeamsAppsRequestBuilder.TeamsAppsRequestBuilderPostRequestConfiguration(
query_parameters = query_params,
)

await graph_client.app_catalogs.teams_apps.post(request_configuration = request_configuration)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following example shows the response.

HTTP/1.1 201 Created
Location: https://graph.microsoft.com/beta/appCatalogs/teamsApps/e3e29acb-8c79-412b-b746-e6c39ff4cd22

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps/$entity",
  "id": "e3e29acb-8c79-412b-b746-e6c39ff4cd22",
  "externalId": "b5561ec9-8cab-4aa3-8aa2-d8d7172e4311",
  "displayName": "Test App",
  "distributionMethod": "organization"
}

Example 3: Approve or reject an app pending review

Request

The following example shows a request.

PATCH https://graph.microsoft.com/beta/appCatalogs/teamsApps/a761ad07-22ef-4a53-9feb-2837c8ad4a84/appDefinitions/YTc2MWFkMDctMjJlZi00YTUzLTlmZWItMjgzN2M4YWQ0YTg0IyMxLjEuOCMjU3VibWl0dGVk
Content-type: application/json
If-Match: InFtSStsNVJHVWdzWUJRU2ZVWGp4RWc9PSI=

{
  "publishingState":"published"
}

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('a761ad07-22ef-4a53-9feb-2837c8ad4a84')/appDefinitions/$entity",
    "id": "YTc2MWFkMDctMjJlZi00YTUzLTlmZWItMjgzN2M4YWQ0YTg0IyMxLjEuOCMjUHVibGlzaGVk",
    "teamsAppId": "a761ad07-22ef-4a53-9feb-2837c8ad4a84",
    "azureADAppId": null,
    "displayName": "Ducks",
    "version": "1.1.8",
    "requiredResourceSpecificApplicationPermissions": [],
    "publishingState": "published",
    "shortdescription": "quaerat quasi magnam. slight change. 5",
    "description": "Aliquid placeat animi debitis accusamus. Non perferendis ullam. Quis est consequuntur vitae provident. Sunt laudantium id aut. slight change 5",
    "lastModifiedDateTime": null,
    "createdBy": null
}

Example 4: Publish an app with an error in the app manifest to the app catalog

Request

The following example shows a request.

POST https://graph.microsoft.com/v1.0/appCatalogs/teamsApps
Content-type: application/zip

[Zip file containing a Teams app package]

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "error": {
        "code": "BadRequest",
        "message": "name | Required properties are missing from object: [].; developer.websiteUrl | String \"hs://www.yo.com\" does not match regex pattern \"^[Hh][Tt][Tt][Pp][Ss]?://\".",
        "innerError": {
            "code": "UnableToParseTeamsAppManifest",
            "message": "name | Required properties are missing from object: [].; developer.websiteUrl | String \"hs://www.yo.com\" does not match regex pattern \"^[Hh][Tt][Tt][Pp][Ss]?://\".",
            "details": [
                {
                    "code": "SchemaError_Required",
                    "message": "Required properties are missing from object: [].",
                    "target": "name"
                },
                {
                    "code": "SchemaError_Pattern",
                    "message": "String \"hs://www.yo.com\" does not match regex pattern \"^[Hh][Tt][Tt][Pp][Ss]?://\".",
                    "target": "developer.websiteUrl"
                }
            ],
            "date": "2024-01-18T21:47:58",
            "request-id": "d1878136-bc88-421a-b342-c3d883db31a1",
            "client-request-id": "d1878136-bc88-421a-b342-c3d883db31a1"
        }
    }
}

Publish teamsApp

Permissions

HTTP request

Query parameters

Request headers

Request body

Response

Examples

Example 1: Publish an app to the app catalog

Request

Response

Example 2: Upload a new application for review to an organization's app catalog

Request

Response

Example 3: Approve or reject an app pending review

Request

Response

Example 4: Publish an app with an error in the app manifest to the app catalog

Request

Response

Feedback

Feedback

Additional resources

Publish teamsApp

Permissions

HTTP request

Query parameters

Request headers

Request body

Response

Examples

Example 1: Publish an app to the app catalog

Request

Response

Example 2: Upload a new application for review to an organization's app catalog

Request

Response

Example 3: Approve or reject an app pending review

Request

Response

Example 4: Publish an app with an error in the app manifest to the app catalog

Request

Response

Related content

Feedback

Feedback

Additional resources