Link Teams Integration From Tab

POST

/org/:org_id/project/:project_id/integration/:integration_id/teams/tab-link

POST

/api/v1/org/:org_id/project/:project_id/integration/:integration_id/teams/tab-link

$ curl -X POST https://app.rightbrain.ai/api/v1/org/org_id/project/project_id/integration/integration_id/teams/tab-link \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "teams_sso_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY1NmVkZWJkLTcyOWItNDhjNS1hYjk3LTFiYjgzNDM3ZGY5MyJ9...",
>   "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
>   "team_id": "19:[email protected]"
> }'

1 {
2   "auth_state": "connected",
3   "installation": {
4     "teams_installation_id": "019a5f1d-6ea4-7d27-a18b-7f40ad5e9163",
5     "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
6     "team_id": "19:[email protected]",
7     "status": "active",
8     "created": "2024-01-16T13:33:25.247662Z",
9     "modified": "2024-01-16T13:41:07.512883Z",
10     "team_name": "Meridian Freight Operations"
11   },
12   "auth_state_reason": null
13 }

Link the Teams team the caller is signed in to with this integration, using the tab’s SSO token as proof of tenant and team.

The bot must already have been added to that team: this operation links an installation the platform has observed, and never creates one. The Teams user calling it must also be the user who added the bot — there is no administrative override. On success the installation becomes active, the integration’s default auth principal moves to connected, and the team’s channels are synchronised; a channel-sync failure is logged and does not fail the request.

Answers 403 when the SSO token is invalid, expired, or issued for a different tenant than tenant_id. Answers 409 for the three link conflicts, which the response body distinguishes: teams_installation_not_observed when the bot has not been seen in that tenant and team, teams_installation_already_linked when that installation belongs to another integration, and teams_installation_not_verified or teams_installation_user_mismatch when the caller did not add the bot. Answers 422 when integration_id names an integration that is not of type teams, and 503 when the Teams bot is not configured on this deployment.

team_name, channel_id, channel_name and content_url are accepted by the request model but are not read by this operation.

Link the Teams team the caller is signed in to with this integration, using the tab's SSO token as proof of tenant and team. The bot must already have been added to that team: this operation links an installation the platform has *observed*, and never creates one. The Teams user calling it must also be the user who added the bot — there is no administrative override. On success the installation becomes `active`, the integration's default auth principal moves to `connected`, and the team's channels are synchronised; a channel-sync failure is logged and does not fail the request. Answers 403 when the SSO token is invalid, expired, or issued for a different tenant than `tenant_id`. Answers 409 for the three link conflicts, which the response body distinguishes: `teams_installation_not_observed` when the bot has not been seen in that tenant and team, `teams_installation_already_linked` when that installation belongs to another integration, and `teams_installation_not_verified` or `teams_installation_user_mismatch` when the caller did not add the bot. Answers 422 when `integration_id` names an integration that is not of type `teams`, and 503 when the Teams bot is not configured on this deployment. `team_name`, `channel_id`, `channel_name` and `content_url` are accepted by the request model but are not read by this operation.

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

integration_idstringRequiredformat: "uuid"

org_idstringRequiredformat: "uuid"

The unique identifier of the organization.

project_idstringRequiredformat: "uuid"

The unique identifier of the project.

Request

This endpoint expects an object.

teams_sso_tokenstringRequired>=1 character

tenant_idstringRequired<=64 characters

team_idstringRequired<=255 characters

team_namestring or nullOptional<=255 characters

channel_idstring or nullOptional<=255 characters

channel_namestring or nullOptional<=255 characters

content_urlstring or nullOptional<=2048 characters

Response

Teams installation linked to the integration

auth_statestring

installationobject

auth_state_reasonstring or nullOptional

Errors

400

Bad Request Error

403

Forbidden Error

422

Unprocessable Entity Error