The short version
- Your Spanner users can ask Microsoft 365 Copilot to work in the Spanner document they have open. The Spanner agent passes each request through our cloud service to Spanner on the user's PC.
- Your IT team sets it up once, in six steps. There are no keys or secrets to hand out.
- Each user needs Microsoft 365 Copilot, Copilot Business or Copilot Chat, and Spanner 2.5 or later.
- Spanner connects out over HTTPS. Nothing connects into your PCs.
- For where your data goes when an AI app uses Spanner, see Using Spanner with AI apps.
How it works
A Spanner user types a request in Microsoft 365 Copilot. The Spanner agent passes it to our cloud service, the Spanner AI API, which relays it to Spanner on that user's PC.
- Sign-in. Microsoft Entra ID signs the user in, and Copilot sends our service a token signed by Microsoft. The token's tenant ID tells us which organisation the user belongs to.
- Session key. When Spanner connects, it shows a short code, such as
abc-xyz. The user gives it to Copilot, which ties the conversation to that user's Spanner. The key changes every time Spanner connects. - One approval per organisation. Your IT admin approves Spanner once for the whole organisation. There are no keys or secrets to hand out.
- Changes. Copilot asks the user to confirm each change before it runs, and changes go into Spanner's undo history.
What you need
| Who | Needs | Why |
|---|---|---|
| Each Spanner user | A Microsoft 365 work account with Microsoft 365 Copilot, Copilot Business or Copilot Chat | To use the Spanner agent in Copilot |
| Each Spanner user | Spanner 2.5.0.0 or later, with the cloud connection | Copilot works on the document open in Spanner |
| Your IT team | AI Administrator or Global Administrator role | To upload and deploy the Spanner agent |
| Your IT team | Cloud Application Administrator, Application Administrator or Global Administrator role | To approve the Spanner AI API |
| Your network | Outbound HTTPS (port 443) to spanner-ai-api.calmsmoke-8a7b20c5.uksouth.azurecontainerapps.io | Spanner keeps one long-lived connection open to our service |
| Us | Your Microsoft 365 tenant ID | To link your organisation to its Spanner licence |
Setting it up
Your IT team does six things once: check the agent policy, send us your tenant ID, approve the Spanner AI API, deploy the agent, check the network, and run a pilot.
-
Check the agent policy
In the Microsoft 365 admin center, go to Copilot › Settings › Data access › Agents, or Agents › Settings › Agent and plugin access. Make sure agents from external publishers are allowed for your Spanner users.
-
Send us your tenant ID
You'll find it at entra.microsoft.com › Entra ID › Overview › Tenant ID. It isn't secret. Email it to enquiries@catmantoolkit.com and we'll link it to your Spanner licence. Until we do, Copilot requests from your organisation are refused.
-
Approve the Spanner AI API for your organisation
Role: Cloud Application Administrator, Application Administrator or Global Administrator- Open this address, with your tenant ID in place of
<tenant-id>:https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=00ed5ac1-08c6-439b-8107-227236c86f1d - Sign in, review the permissions and select Accept.
- The browser may then show a Teams page or a blank page. That's expected: the approval is already saved.
Check: entra.microsoft.com › Entra ID › Enterprise applications lists the Spanner app, and its Permissions page shows admin consent granted.
- Open this address, with your tenant ID in place of
-
Upload and deploy the Spanner agent
Role: AI Administrator or Global AdministratorWe send you the agent package, a .zip file.
- In the Microsoft 365 admin center, go to Agents › All agents › Upload custom agent › Choose File and pick the .zip file.
- Check the name, icon and host products, then select Next.
- Choose the users. Start with a pilot group and widen it later. Select Next.
- Review the permissions and capabilities, then select Next and Finish deployment.
To change who has it later: Agents › All agents › Spanner › Users.
-
Check the network
Spanner PCs need outbound HTTPS (port 443) to
spanner-ai-api.calmsmoke-8a7b20c5.uksouth.azurecontainerapps.io. Nothing connects into the PC.Spanner holds one connection open for the whole session. Proxies that inspect SSL traffic, such as Zscaler or Netskope, can cut or buffer it. If Spanner keeps disconnecting, exclude this address from inspection.
Test: connect Spanner on a corporate PC and leave it for 5 minutes. If it stays connected, the network is fine.
-
Run a pilot
One user tries Spanner in Copilot, then tells us how it went.
Security and data
Copilot reaches a user's Spanner only with a Microsoft-signed sign-in plus that user's session key, and no keys or secrets are handed to your organisation.
| Topic | Answer |
|---|---|
| Hosting | The Spanner AI API runs on Azure Container Apps in UK South, operated by Productive Insights Ltd. |
| Sign-in | Microsoft Entra ID. Our service checks each token's signature, that it's meant for Spanner, the access_as_user permission and the tenant ID. |
| Which organisations get in | Only tenant IDs registered with us. Others are refused and logged. |
| Permissions requested | Sign-in to the Spanner AI API (access_as_user). Spanner doesn't ask for access to mail, files or Teams. |
| Reaching a user's Spanner | Only with the session key Spanner shows on that PC. It changes every time Spanner connects. |
| Document data | Passes through our service in memory and isn't stored there. |
| What our service stores | For each session: the session key, your saved merchandising rules and which of our servers holds the connection, kept for up to 10 days. |
| Inside Copilot | Data that Copilot reads from Spanner, such as products and sales, becomes part of the Copilot conversation under your organisation's Microsoft 365 Copilot terms. |
| Changes to documents | The user confirms each change in Copilot before it runs, and changes can be undone in Spanner. |
| Network | Spanner connects out over HTTPS on port 443. No inbound ports are opened. |
See also Using Spanner with AI apps, our privacy policy and our data processing terms.
Troubleshooting
Most problems come from a missing setup step or an old session key.
| What you see | Likely cause | Fix |
|---|---|---|
| Spanner isn't listed under Agents in Copilot | It hasn't been deployed to that user yet | Agents › All agents › Spanner › Users, then allow time for it to appear |
| "This plugin is blocked by your organization's policy" | The agent policy excludes it | Step 1 |
| Sign-in asks for admin approval, or fails with a "resource principal not found" error | The Spanner AI API isn't approved in your tenant | Step 3 |
| Copilot says Spanner refused the request | Your tenant ID isn't registered with us yet | Step 2. We can find your tenant ID in our log |
| "No Spanner session key provided", or the key isn't recognised | A missing or old session key | Give Copilot the key Spanner shows now |
| "Spanner Desktop isn't connected" | Spanner is closed or disconnected | Open Spanner, connect it and give Copilot the new key |
| Spanner disconnects after a few minutes | A proxy is cutting the long-lived connection | Step 5 |
| A command times out | It ran for longer than 90 seconds | Check Spanner first, because the change may have finished, then ask for smaller batches |
| Copilot says a confirmation expired, but Spanner made some of the changes | Copilot dropped a reply that was too large | Undo the partial changes in Spanner, or ask Copilot to check the document and run only what's missing |
Still stuck? Email enquiries@catmantoolkit.com.