Custom integrations
What a custom integration is, what you receive when your app is registered, how a user installs it, and what an installation can reach.
A custom integration is your app, registered with Blue Reacher so that users can install it into their account. It is the only way to get API credentials. There are no static API keys.
Register your app
Register the app on the Custom integration page of the dashboard at app.bluereacher.com, or ask Blue Reacher support to register it for you. The registration holds:
| Item | What it is |
|---|---|
| Name | What users see on the consent screen. |
client_id | The public id of your app. It appears in the install URL. |
client_secret | The secret your server sends when exchanging codes and refreshing tokens. Keep it server-side. |
redirect_uri | Your callback URL. The authorization code is delivered there, so it must match exactly. |
| Scopes | The permissions your app asks for at install. See Scopes. |
| Rate limits | The request budgets for the app. The defaults are on Rate limits. |
Changing the registered scopes takes effect on the next API call from every installation. No reinstall is needed.
How a user installs it
- Your app sends the user's browser to
https://app.bluereacher.com/integrations/install/<CLIENT_ID>?redirect_uri=<YOUR_CALLBACK>&state=<RANDOM>. - The user signs in if needed and sees the consent screen with your app's name and scopes.
- On Install, the browser returns to your callback with a single-use code. On Cancel, it returns with
error=access_denied. - Your server exchanges the code for an access token and a refresh token.
The full flow, with every request and response, is on Authentication. The quickstart walks through it once.
One install, one user
Each installation belongs to the user who consented. Tokens are bound to that installer:
- A token reaches only the workspaces, devices, contacts and messages that belong to the installer. A leaked token cannot read another account's data.
- Most calls take a
workspace_id. List the installer's workspaces withGET /v1/workspaces. A workspace that belongs to someone else answers404. - Store tokens per user, not per app. If several users install your app, you hold a token pair for each one.
GET /v1/integration/me tells you which user and which scopes a token carries. Use it as a credentials probe before anything else. See Probe.
Removing an installation
Blue Reacher can revoke an installation, after which every token for it answers 401. There is no client-facing uninstall endpoint yet. If a user removes your app on your side, discard their tokens and contact support to have the installation suspended.
Next
- Authentication: the OAuth flow end to end.
- Scopes: what to request.
- Token format: what a token contains.
- API reference overview: the routes your installation can call.