Tornevall Networks

← Back to docs

Microsoft 365 Copilot Connector

Microsoft 365 Copilot Connector

Tools exposes Microsoft 365 Copilot through two entry points:

  • /admin/copilot for administration, Microsoft account connection and direct testing.
  • POST /api/ai/copilot/respond for external API clients.

Both paths call Microsoft 365 Copilot directly through Microsoft Graph. Copilot does not use OpenAI Engine and has no OpenAI fallback.

Authentication model

Microsoft 365 Copilot Chat requires delegated authentication with a work or school account. Application-only authentication and personal Microsoft accounts are not supported for Copilot Chat.

The environment-backed Copilot setup uses the Copilot Microsoft application profile and the same configured tenant as the licensed Copilot resource tenant. Other Microsoft integrations can continue to use their own Microsoft profile independently.

The supported sign-in sequence is:

  1. A tenant administrator grants the required delegated Microsoft Graph permissions from /admin/copilot when tenant-wide consent is required.
  2. The Copilot user chooses Connect/reconnect Microsoft 365 Copilot.
  3. Tools starts the normal browser authorization-code flow and explicitly asks Microsoft to select an account.
  4. The user signs in with the work or school account that has the Microsoft 365 Copilot entitlement.
  5. Tools validates the returned token tenant, application client and required Graph permissions before the connection is marked ready.
  6. A direct prompt test is sent to Microsoft 365 Copilot.

Tools does not use Microsoft device-code authentication for this web-app flow. A tenant may intentionally block device-code authentication through Conditional Access even when the account credentials are valid.

Admin flow

On /admin/copilot, an administrator can:

  • manage Copilot tenant setups
  • delegate a setup to a Tools user
  • grant tenant-wide Microsoft consent where required
  • connect or reconnect a licensed Microsoft account
  • run a real Microsoft 365 Copilot prompt test

The direct test creates a conversation through POST /beta/copilot/conversations and sends the prompt through POST /beta/copilot/conversations/{conversationId}/chat. A test succeeds only when Microsoft returns an actual Copilot response.

Required Microsoft Graph permissions

The reconnect flow requests the OAuth helper scopes offline_access, openid, profile and User.Read, together with these Copilot permissions:

  • Sites.Read.All
  • Mail.Read
  • People.Read.All
  • OnlineMeetingTranscript.Read.All
  • Chat.Read
  • ChannelMessage.Read.All
  • ExternalItem.Read.All

Some permissions require administrator approval. If any required Graph permission is missing, Tools stops the Copilot request and asks for consent/reconnect instead of falling back to another AI provider.

Connection validation

Tools validates that:

  • the delegated token belongs to the configured Copilot tenant
  • the token was issued to the configured Copilot application
  • all required delegated Graph permissions are present
  • the connected account is usable before Microsoft Graph is called

A Microsoft 365 Copilot entitlement is also required for the signed-in user.

When Microsoft says "You don't have access"

A successful password/sign-in followed by an access-denied page does not prove that the Copilot credentials are wrong. The tenant can reject the authentication or authorization because of Conditional Access, application assignment, consent policy or another Entra access rule.

Use the normal browser reconnect from /admin/copilot, not device-code authentication. If Microsoft still denies access, inspect the Microsoft Entra sign-in event for the failed attempt and use its error/AADSTS code to identify the exact policy or permission that blocked the request. If administrator consent has not been granted for the required Graph permissions, run Grant tenant admin consent + reconnect first.

External API

External clients use:

POST /api/ai/copilot/respond

The client authenticates to Tools with a bearer token that has the ai.copilot scope. Tools resolves that token to a Tools user and uses the user's delegated Microsoft 365 Copilot connection.

Example:

curl -X POST "https://tools.example.test/api/ai/copilot/respond" \
  -H "Authorization: Bearer YOUR_TOOLS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_prompt": "Summarize this issue in three bullets.",
    "response_language": "en",
    "use_web_search": false
  }'

At least one of context and user_prompt is required. Supported request fields include context, user_prompt, modifier, previous_reply, mood, custom_mood, instructions, custom_instruction, response_language, use_web_search, web_search_required and an administrator-only connector_slug override.

Microsoft 365 Copilot controls model selection. OpenAI model names, reasoning effort, temperature and OpenAI token limits do not control this connector.

A successful response includes ok: true, the Microsoft 365 Copilot response text, connector metadata and diagnostics identifying Microsoft Graph/Microsoft 365 Copilot as the upstream provider.

Live release validation

Copilot changes are not considered live-verified by application credentials alone. The live CI gate must receive a real answer from Microsoft 365 Copilot.

The preferred live test calls the deployed Tools Copilot API with a protected bearer token whose Tools user has already completed browser OAuth with the licensed Microsoft account. A pre-seeded delegated Microsoft refresh token issued by the same browser authorization-code flow can be used as a direct Graph fallback.

The live gate does not bootstrap with device code. It fails when no delegated live identity is configured, when tenant/client/scope validation fails, or when Microsoft returns no usable Copilot answer. Authentication tokens and secrets are never printed.

Common API errors

  • 401: the Tools user could not be identified.
  • 403: Copilot access, tenant validation or required Microsoft Graph permission is missing.
  • 409: the Microsoft account is missing or needs reconnecting.
  • 422: the prompt or connector request is invalid.
  • 502: Microsoft Graph returned an unusable response or could not be reached.

Copilot request operations are audit logged separately from the normal application log. OAuth operations record safe action/result and diagnostic identifiers without storing OAuth state, authorization codes, access tokens, refresh tokens or client secrets.