Mini app server access (background access)
A catalog mini app can ask for server access, shown in the panel as Background access.
- Plan
- Depends on your plan · Which plan do I need?
- Who can use this
- Developer, Account owner
A catalog mini app can ask for server access, shown in the panel as Background access.
A catalog mini app can ask for server access, shown in the panel as Background access. It lets the app's own server call the REST API for a workspace when nobody has the app open, for example to run reminders or sync jobs. It is opt-in: an app that does not ask for it works exactly as before.
If it asks for background access, the consent screen has a section "When nobody has the app open, it can:" with one line per permission.
This happens when the app was installed before it offered background access, or when nobody approved it at install. Approve opens the review of what the app asks for. Saving it switches access on and sends the app a new connection code.
To give it a fresh credential, click Reset (asks for your two-factor code).
The catalog entry declares background access, the server scopes it needs and an install hook URL. You receive a public client id and a client secret, shown once. After a secret rotation the old secret stays valid for 24 hours.
When a workspace installs your app, your install hook receives a signed installed event with a single-use install code, valid for 10 minutes. The hook never carries the credential itself.
Your server sends the client id, client secret and install code to the installation credential endpoint and receives the installation credential once. Store it encrypted, keyed by installation id.
Exchange the credential for an access token (valid 10 minutes) and call /v1/* with Authorization: Bearer <access token>.
Others: disabled, enabled, scopes_changed, upgraded.
The SDK's server half has helpers for each step (verify the hook, redeem the code, an API client that renews tokens, an encrypted credential store). The starter project shows a complete hook and an example background job.
mcp:read, crm:write, inbox:write, messaging:write, kb:write, bots:write, and apps:self (the app manages its own sub-apps only).miniapps) and, for paid apps, the app's add-on. Check Billing → Current Plan.RateLimit-Policy and RateLimit headers, and a 429 always has Retry-After.Do it with Copilot
(shows each app and its settings)
| What you see | Why | What to do |
|---|---|---|
| Card says "Not approved yet" | The app was installed before it offered background access, or nobody approved it | Click Approve and save the review |
| Card says Not connected | The app never redeemed its install code | Click Retry; ask the app's publisher to check their hook and storage |
invalid_install_code | Code expired, used, or replaced by a newer delivery | Use the code from the latest hook delivery |
401 token_revoked or invalid_grant | Access was turned off, reset or uninstalled | Reconnect: a manager turns it on again, or uses Retry / Reset. Do not loop retries |
401 token_expired | Access token older than 10 minutes | Get a new token (the SDK does this) |
403 installation_inactive | App disabled or workspace suspended | Pause work for that workspace |
403 insufficient_scope | The call needs a scope the app was not granted | Ask for it in a new version |
502 upstream_unauthorized | A service behind the API refused | Not your app's fault; retry later |