Integrations

What it is#

A catalogue of the tools a workspace already uses, each with a connection that is proved before it is stored. Connecting spends the credential against the vendor first — a token that does not answer is never saved, and the error you see is the vendor's own words.

The catalogue distinguishes what the credential can do from what the product does with it, because merging those two is how a page comes to show thirty-seven buttons that do nothing.

How to get there#

Admin → Integrations. Seeing the connected tools needs integration.view, which members hold; connecting and disconnecting needs integration.manage. Issuing an API token is a third key, integration.api_token.

The member-facing list shows only what is connected — never a vendor's error text and never a credential field.

How to use it#

Read a readiness badge#

Connect a tool that takes a token#

1. Admin → Integrations, find the card, press Connect.
2. Fill in the fields the card asks for. Each hint names where in the vendor's own console to get it, and asks for the narrowest credential that works — a Slack bot token rather than a user token, a fine-grained GitHub token, a Notion integration that reads only pages shared with it.
3. Pressing Connect calls the provider. A malformed credential never reaches the network; a rejected one is a refusal carrying the vendor's message.
4. Test re-runs the read-only check. Send test delivers a real message, which is why it is a separate button.

Connect a tool that needs your own OAuth app#

Gmail, Outlook Email, both calendars, Google Drive and OneDrive do not take a token — they take an app.

1. Your directory administrator registers an internal OAuth application with the vendor, using the redirect URI the card displays, matched byte for byte, and the scopes the card lists.
2. Paste the client id and secret, then press Authorize. The connection sits as pending until somebody completes the consent screen.
3. The vendor sends the browser back; the connection becomes connected and verified, and the account it reached is shown.
4. From then on the refresh token is the durable credential and is refreshed before every use.

This is the only arrangement a security review accepts. A single Projectri-owned Google client would put every customer's mail through one consent screen and one revocation switch.

Connect a mailbox that has no OAuth#

Yahoo Mail and any custom IMAP host take an app password over IMAP and SMTP. Yahoo's mail API is partner-only, so an "Authorize with Yahoo" button would grant profile access and nothing this product could spend.

Send a webhook to your own system#

1. Admin → Webhooks, add an endpoint. It needs integration.manage — whoever can add one can stream this workspace's tasks, tickets and invoices to an address of their choosing, which is the same authority as connecting a service.
2. Subscribe it to event types. The published set is deliberately small: tasks, projects, tickets, work orders, escalations, time entries, invoices, estimates, milestones, sprints and customer contacts, each with the actions that make sense for it.
3. Every delivery carries X-Projectri-Signature — a timestamp and an HMAC over the timestamp and the body, so a captured request cannot be replayed.

What it affects#

What actually has an adapter#

Live — Slack (bot token), Microsoft Teams (incoming webhook), Discord (channel webhook), Zapier (catch hook), GitHub, GitLab, Jira, Linear, Notion, Segment, Amplitude, Gmail, Outlook Email, Yahoo Mail, custom IMAP, Google Calendar, Outlook Calendar.

Verified connection — Bitbucket, Sentry, Figma, Miro, Dropbox, Box, Google Drive, OneDrive.

API only — Oracle NetSuite, SAP, Microsoft Dynamics 365, Oracle Fusion Cloud, Sage Intacct, QuickBooks, Xero, Zoho Books, Odoo, Tally, a CSV/SFTP drop, and a custom finance API.

Everything an automation rule can send to is in the Live list, and only there.

The consequences#

• Connecting a finance system does something structural. It creates an ERP connection whose ownership switches decide which records Projectri then refuses to let anyone edit. That is why those cards open a different form: a Connect button that quietly made invoices read-only would be worse than no button.
• A revoked credential turns the card red. Delivery outcomes are written back onto the connection, so a webhook somebody deleted at the far end shows up as a broken integration rather than as a log nobody reads.
• A connection is per workspace, not per person. An administrator makes it once for everybody. Personal calendar grants are a different, separate thing.
• Credentials are write-only over the API. Reading a connection returns whether it is configured plus a non-secret hint — the Slack workspace, the mailbox address — never the value.
• URLs and hosts are filtered. A webhook URL must be HTTPS and must not resolve to something private, and an IMAP host goes through the same guard. The server fetches these with our network position, so an unfiltered address turns the console into a request forger.

On mobile#

Connecting an integration is web-only — it is one-time workspace configuration, often involving a vendor console open in another tab. The phone shows the results everywhere they apply: a calendar that syncs, a channel that receives.

Limits and gotchas#

• "Verified" is not "Live", and the difference is deliberate. Drive and OneDrive prove their token and have no feature reading from them yet. Inventing one to earn a better badge is exactly what the readiness column exists to prevent.
• A vendor's redirect URI must match byte for byte. Both Google and Microsoft compare it exactly; a trailing slash is a failed handshake.
• Microsoft rotates refresh tokens, so a connection is written back immediately after every refresh. Do not be surprised that the stored credential changes without you touching it.
• **The finance cards are usable today, through our API, not through a vendor client.** They are badged blue rather than amber for that reason — an integration team can build against them now.
• **A third-party OAuth app can reach your data without appearing on this page's own list.** It is shown here too, in a state of its own, so that nothing about it can be mistaken for a connector we wrote. Whether we have reviewed such an app is a separate fact and is shown separately.

Related#

• Integrations — the screen itself, card by card.
• Webhooks — outbound events to your own system.
• MCP servers — connecting Projectri to an external tool server.
• Automation — the rule action that spends these credentials.
• Finance and ERP — what connecting a ledger takes over.