Integrations
An admin-only card in Workspace settings connects Can to another app. Integrations mints a credential that app uses to call Can's API as itself — a member of your workspace, with a name, an audit trail, and a revoke button.
The card is visible only to workspace admins, and an integration is workspace-wide: one connection covers every board in the workspace.
Three kinds of credential
Can's REST API accepts three credentials, and which one you want depends on who is acting.
| Credential | Prefix | Acts as | Comes from |
|---|---|---|---|
| OAuth 2.0 access token | — | You, through a client you approved | The OAuth flow, per session |
| Personal access token | rft_can_ |
You | API tokens in workspace settings |
| Workspace integration credential | rfi_can_ |
The connection itself | Integrations in workspace settings |
The distinction that matters: a personal access token is you acting as you, so it carries your memberships everywhere you are a member and should never be handed to another app or another person. An integration credential is another app's workspace acting as itself — a member of exactly one workspace, and of nothing else.
The first two are covered in REST API and OAuth. The rest of this page is the third.
What an integration is
Connecting an app's workspace to yours creates a member in your workspace, not a hidden key. The member's id is integration:<app>:<origin workspace id> — say integration:acme:abc123 — and the credential Can mints names that member as its principal.
That has consequences worth knowing:
- It appears in the member list, with the display name you gave it and an
integrationbadge where a role would be. There is no role to pick: an integration is a plain member. - It is scoped to one workspace by construction. The principal exists in exactly one member list, so whatever else the connecting admin can see, the credential cannot reach it.
- Any admin can revoke it, and it outlives the admin who installed it leaving or being demoted.
- Every request is authorized live against that member doc, the same read that authorizes a human.
Connect an app
In Workspace settings → Integrations:
- Enter the app slug — lowercase letters and digits, naming the app on the other side. It becomes the middle segment of the member id.
- Paste the origin workspace id — the id of the workspace on the other side, from that app's settings.
- Give it a display name, up to 100 characters. It is what shows in the member list, so name the connection:
Acme Support. - Press Connect.
Can mints an rfi_can_… token and shows it exactly once. Copy it before you dismiss the banner; only a hash is stored, so a lost credential means revoking and connecting again. An origin workspace can be connected once — connecting the same one twice is refused until you revoke the first.
Minting requires being signed in to Can. An OAuth token, a personal access token, or an integration credential cannot create another integration.
Revoke
The trash button beside an integration deletes the member doc and every token minted for that principal. Access stops on the connected app's next request: verification is a live lookup, so there is no propagation delay.
Removing the integration from the member list disables the credential too, for the same reason — a principal with no member doc gets a 404 from every workspace endpoint. The Integrations card is the tidier gesture, because it also clears the token record.
Attribution
Requests from an integration can carry an x-on-behalf-of header: JSON holding a display name and the origin app's own person key, never an email, naming whoever triggered the action over there. Can records that claim on the ticket's activity entries, and the ticket's History tab reads the whole line as Acme Support on behalf of Maya: the integration's display name as the actor, then the claim. Activity entries also record a via value of integration:<display name>, which rides along in board exports; History leaves that one off, since the actor already carries the name.
Treat the claim as audit-grade, not authorization-grade: it is exactly as trustworthy as the integration you installed. Permissions come from the member doc; the header never grants anything.