Connecting outside systems like GitHub

An outside system, such as GitHub, becomes available to your Coworkers in three steps: you save a connection that holds your own OAuth app, you connect your own account through it, and you attach the system's tools and turn on the functions Coworkers may use. Then each Coworker's Supervisor enables the system for the Coworkers that need it. Each person connects their own account, and a Coworker acting for someone uses that person's account. See Connecting your accounts.

You need the admin ability. The connections live on the Connectors page, in the same list as connectors your Coworkers have built.

Create the OAuth app in the system#

You create the app in the outside system's own developer console, under your organization if the app should belong to it. Step-by-step guides cover the three systems with the most involved setup: Connect Microsoft 365, Connect Google Workspace and Connect Atlassian (Jira and Confluence). For GitHub:

1. Open https://github.com/settings/developers, choose OAuth Apps, then New OAuth App.
2. Give the app a name people will recognize. The homepage URL can be your Workforce Intelligence address.
3. Set the authorization callback URL to the redirect URI shown on the connection form, exactly as written. It is your public address followed by /api/integrations/oauth/callback.
4. After GitHub creates the app, copy its client ID, then generate a client secret and copy that too. GitHub shows the secret only once.

Add the connection#

1. Open Settings, select Review on the Connectors card, then select Add a connection. The list also holds SharePoint, tagged For Knowledge Bases; see Connecting SharePoint for that one.
2. Search the list of systems and pick one to fill in what is already known, or select Blank form for a system that is not listed.
3. Read Set up followed by the system's name. It repeats the steps above for the system and shows Redirect URI to register. Select Open the developer console to go to the system's page.
4. Fill in the form.
5. Select Add connection.

Field	What to enter
Display name	The name your team sees in the list, such as GitHub.
Client id	The client ID from the system's developer console.
Client secret	The client secret from the same place. It is stored encrypted and never shown again.
Environment variable name	The name scripts read to get a person's access token, for example os.environ["GH_TOKEN"]. It cannot change once anyone has connected.
Authorize URL	Where people are sent to sign in. Prefilled for listed systems.
Token URL	Where the system exchanges the sign-in for a token. Prefilled for listed systems.
Profile URL	Optional. Used to show which account someone connected as; a Coworker acting for that person is told the same name.
Revocation URL	Optional. When someone disconnects, WI asks the system to revoke their token here.
Scopes (a Permissions checklist for systems with a curated list)	Optional. For Microsoft, Atlassian, Jira, Slack, Google, Linear and GitHub, a checklist replaces the plain field: see "Choose permissions with the checklist" below. For every other system, the permissions your Coworkers need in this system, written the way the system expects them (most use spaces between scopes; Slack, Linear and Figma use commas). Read-only scopes are prefilled for GitHub, Google, Slack, Linear, Microsoft, Asana, GitLab, Dropbox, Figma, Jira, Atlassian and Airtable, for example read:user repo for GitHub. The setup steps name the write scopes to add when Coworkers must change things. Notion has no scopes, so leave the field empty: what Coworkers can do comes from the capabilities you enable on the Notion connection. Other listed systems start empty: look up the scopes in the system's own documentation.
Notes for Coworkers	Optional, up to 2,000 characters. On a connection limited to Functions only, the field adds "In Functions only, Coworkers get the function guide, plus the notes you write here." Anything a Coworker should know to use this system well, such as which address to call or which project to use. Coworkers you turn the system on for see these notes with the system's name in their instructions, so write them as plain guidance and keep secrets out. A note is prefilled for Atlassian and Jira (their access tokens work only on api.atlassian.com, after looking up the site's cloud id), GitHub, Slack, Linear, Microsoft, Notion and Google; edit or clear it as you like.
Use PKCE	A checkbox. Turn it on if the system requires PKCE. Some systems reject sign-ins without it. It is already on for Airtable, Canva, Etsy and Twitter (v2).

Choose permissions with the checklist#

For systems with a curated list, the form shows Permissions as a checklist. Each permission has a plain name, a Read or Write badge, a one-line description with the exact scope in brackets, and a tick box. The ticked permissions are saved as the same space-separated scopes described above; a new connection starts with the read-only defaults ticked. Anything the list does not cover goes in Other permissions, a plain text box, and is kept as you wrote it. When the connection already has attached functions that more permissions would unlock, a line under the checklist reads "Adds these functions:" followed by their names. The warning below about connecting again applies to every change.

The scopes decide what Coworkers can do in the system, so start with read-only access and add write access only when you need it. Ticking a permission here does not grant it on its own: turn on the same permissions in the system's own developer app, or the provider will refuse the sign-in or reject calls that need them. If you change them later, people who already connected must connect again.

Some systems need extra settings on the sign-in address. For listed systems these are already part of the Authorize URL, so there is nothing to add: Google and Dropbox include the setting that returns a long-lived sign-in, Jira and Atlassian include the audience and consent settings, and Notion includes owner=user. If you enter a system by hand, add any such settings to the end of the Authorize URL yourself, for example ?access_type=offline. Scopes and the other standard settings WI sends are never repeated.

Every URL must start with https://. Any field can be edited after it is prefilled.

The connection appears as a card named for the system. It reads Not connected or "Connected as" followed by your account, and how many functions are on. Select Connect to link your own account. You must do this before you can attach tools, because your account is used to look up what the system offers. After you sign in with the system you return to the Connectors page, where a message reads, for example, "GitHub is connected. Next, attach its tools below." when the system has a ready-made tool set and none is attached yet (once tools are attached it reads "GitHub is connected."). For a system with no ready-made tool set, it reads, for example, "Atlassian is connected. Turn it on for the Coworkers that should use it." If you cancel on the system's own page, the message reads "You chose not to connect, so nothing was changed." Select Manage to open the card and Hide details to close it. Under Connection settings you can edit the form, and leaving Client secret blank keeps the one on file. Remove connection asks you to confirm, naming what goes with it, and then removes the connection together with its attached tools and their functions, turns it off for every Coworker, and disconnects everyone who connected through it, all at once. You can add it again from the catalog. To take away only the tools, use Remove on the attached tools; the connection stays. Disconnect removes only your own account.

When a person disconnects, WI deletes its stored token and, if the connection has a revocation URL, also asks the provider to revoke it. For a provider without a revocation URL, the token stays valid at the provider until it expires.

Attach tools and turn on functions#

Systems with a ready-made tool set, such as GitHub, and systems whose web API the platform can call for Coworkers, such as Microsoft, Linear, Atlassian, Jira, Slack and Google, show Attach tools. Several services can share one connection: Jira and Confluence use the Atlassian connection, the Microsoft services (Calendar, Mail, Files, Teams, People and Tasks) use the Microsoft one, and Gmail, Google Calendar, Google Drive, Google Docs and Google Sheets use the Google one. Each service is its own offer, named for the service, such as Microsoft Calendar or Jira, with its own Attach tools button and its own functions; when the service name differs from the connection's, the line under it ends "Uses your" followed by the connection's name, "connection." A system can also appear twice, once as a tool server and once as a web API; the line under each name says which ("The tools" followed by the name, or "Ready-made functions for" the name). A system whose web API has no ready-made functions has no Attach tools button; you give Coworkers its Custom requests with the switch described below. For any other system the open card says that no ready-made functions come with it, and the collapsed line omits "No tools attached". You use such a connection by turning it on for the Coworkers that should have it (see the section after next): a Coworker's scripts can then read each person's access through the connection's environment variable, shown in Connection settings, and call the system's own web API with it.

1. In the open card, find Tools and select Attach tools beside the system. For GitHub this lists the functions GitHub offers.
2. Every function is listed with its description, and every function starts turned off.
3. Tick a function to turn it on. A function that is off cannot be found or used by any Coworker. A function that is on can be found and used only by Coworkers the system is enabled for (see the section after next).
4. For each function that is on, choose its default: Allow, Ask or Block.

Default	What happens when a Coworker uses it
Allow	It runs without asking.
Ask	The person the Coworker is acting for is asked first.
Block	It never runs, whatever the person chooses.

Each person can make a function stricter for themselves, never looser than your default. A person who chooses Don't ask again on an Ask function stops being asked for it, but only while its default is Ask. If you change the default to Block, that person's choice no longer applies. A function set to Ask can only run in a conversation, where the person can answer. When a workflow run or a trigger would need to ask, the call is refused and nobody is asked. An unanswered request expires after seven days.

The person who answers is the person the Coworker is acting for. Your admin ability does not let you answer for someone else.

For a web-API system each function carries a Read or Write badge, so you can see which ones change data. A system with no ready-made functions reads "No ready-made functions for this system."

A function the connection's permissions do not cover stays in the list, greyed (for GitHub too: see "GitHub permissions" below), with no tick box or Allow, Ask and Block choice. It keeps its Read or Write badge and says what is missing: "Needs the Calendars.ReadWrite permission. Add it in connection settings." or, when any one of several would do, "Needs one of:" followed by the names. Go to permissions takes you to the Permissions checklist (or Scopes field) in Connection settings. Above the list, a line reads, for example, "2 more functions unlock with more permissions." Within each service the functions you can use come first, and the greyed ones are grouped at the bottom under Needs more permissions. Once you add the permission and Refresh functions, the function can be turned on. If turning one on is refused, the message names the permissions to add.

Refresh functions reads the system's list again. New functions arrive turned off, your choices and everyone's own settings stay, and a function the system no longer offers reads No longer offered by this system. Remove next to the system's name detaches its tools: the functions disappear from the Coworkers' search, and requests waiting on them are dropped. The connection itself stays. A card that reads Needs attention shows the reason beneath it.

What each service offers#

Each service below has its own Attach tools button. A function appears in the list greyed until the connection has one of the permissions in the right-hand column. Functions marked Write change something and should usually start on Ask. Lists return a small first page; Coworkers page on only when asked.

Microsoft (one connection, five services)

Service	Read	Write	Permission that unlocks it
Microsoft Calendar	Calendar view, list events, read an event, list calendars	Create, change and delete events; accept, tentatively accept and decline	Calendars.Read for reads, Calendars.ReadWrite for writes
	Find meeting times (nothing is booked)		Calendars.Read.Shared (or Calendars.ReadWrite.Shared)
	Free/busy schedule		Calendars.ReadBasic (or Calendars.Read, Calendars.ReadWrite)
Microsoft Mail	List and search messages (previews), read a message, read a message body as plain text, list folders and attachments	Save and change drafts, move a message, mark read or unread	Mail.Read for reads, Mail.ReadWrite for drafts, moves and marking
		Send mail, send a draft, reply, reply to all, forward	Mail.Send
Microsoft Files	List and search the person's OneDrive, read an item's details; find SharePoint sites, list their libraries, browse and search a library	Create a folder, upload a small text file (up to 1 MB), delete an item	Files.Read or Files.Read.All for OneDrive reads; Sites.Read.All or Files.Read.All for SharePoint; Files.ReadWrite (or Sites.ReadWrite.All) for writes
Microsoft Teams	List joined teams and channels		Team.ReadBasic.All, Channel.ReadBasic.All
	Read channel messages and replies	Post in a channel or reply	ChannelMessage.Read.All (most organizations need administrator approval), ChannelMessage.Send
	List chats, read chat messages	Send a chat message	Chat.ReadBasic or Chat.Read to list chats, Chat.Read to read messages, ChatMessage.Send or Chat.ReadWrite to send
Microsoft People and Tasks	Search the people the person works with, look up and search the directory, list contacts, To Do lists and tasks, Planner tasks	Create and change To Do tasks	People.Read, User.ReadBasic.All or User.Read.All, Contacts.Read, Tasks.Read, Tasks.ReadWrite

Files are not downloaded: Coworkers get names, sizes and links, and can create small text files. The default Microsoft permissions unlock mail, calendar and OneDrive reads and nothing that sends or changes.

Google (one connection, five services)

Service	Read	Write	Permission that unlocks it
Gmail	Search, read a message (headers and a snippet by default; the whole message on request), read a thread, list labels	Save a draft, send a draft, send an email, reply in a thread, add or remove labels (mark read, archive), move to trash	gmail.readonly for reads; gmail.compose for drafts, sending a draft and sending; gmail.send for sending a new email or reply only; gmail.modify for labels and trash. https://mail.google.com/ covers all
Google Calendar	List calendars and events, read an event, free/busy	Create, change and delete events	calendar.readonly for reads; calendar.events or calendar for writes; calendar.freebusy for free/busy
Google Drive	List and search files, read details, export Docs and Sheets as text, read plain-text files (up to about 4 MB)	Create a folder, create a small text file (up to 1 MB), move a file to the trash	drive.readonly for reads; drive or drive.file for writes
Google Docs	Read a document	Create a document, append text	documents.readonly or documents
Google Sheets	List tabs, read ranges	Overwrite a range, append rows	spreadsheets.readonly or spreadsheets

Coworkers give Gmail plain addresses and text; the platform builds the message. Sending and replying go out immediately as the person, so most administrators set them to Ask.

Atlassian (Jira and Confluence; the Jira connection offers Jira only)

Service	Read	Write	Permission that unlocks it
Jira	Search with JQL, read an issue, list comments, transitions, projects, issue types and boards, read a project, find people, the person's profile, list sprints and a sprint's issues	Create and edit issues, comment, change status, assign, log time	read:jira-work for reads, read:jira-user for people, write:jira-work for writes. Boards and sprints take Jira Software's fine-grained permissions instead: read:board-scope:jira-software with read:project:jira for boards, read:sprint:jira-software for sprints, plus read:issue-details:jira and read:jql:jira to list a sprint's issues
Confluence	Search with CQL, read a page (with its body on request), list spaces and a space's pages, list comments, labels and attachments	Create and update pages, comment, add a label	search:confluence for search and write:confluence-content for labels; pages, spaces, comments and attachments take Confluence's fine-grained permissions: read:page:confluence, write:page:confluence, read:space:confluence, read:comment:confluence, write:comment:confluence, read:attachment:confluence

In the Atlassian developer console, add the User identity API under Permissions (it provides read:me; the form prefills it). It reads only the signed-in person's name and email, with no Jira or Confluence content, and it lets the connection show "Connected as <name>". Without it the sign-in is refused.

Coworkers write Jira descriptions and comments, and Confluence pages, as plain text; the platform converts it to each product's format. Updating a Confluence page replaces its content, and the Coworker must read the page first to pass its next version number.

Slack and Linear are covered by the permission checklist on their connection cards.

GitHub permissions#

The GitHub connection's Permissions checklist lists GitHub's own OAuth scopes with a plain name and a Read or Write badge: repo (public and private repositories), public_repo (public repositories only), repo:status, repo_deployment, repo:invite, security_events, workflow, the repository webhook scopes, read:org, write:org, admin:org, gist, notifications, read:user, user:email, user:follow, user, read:project, project, the package scopes and delete_repo. A bigger scope includes the smaller ones: repo covers public_repo, admin:org covers write:org and read:org, project covers read:project, and user covers read:user, user:email and user:follow. New connections start with read:user repo.

GitHub's functions are read from GitHub each time you Refresh functions, and the connection turns off the ones its permissions cannot serve:

Functions	Offered with one of
Repositories, files, commits, releases, issues, pull requests, labels, discussions, Actions runs, Copilot, search, stars	repo or public_repo
Code scanning, Dependabot, secret scanning and repository security advisories	security_events, repo or public_repo
Teams, team members and organization search	read:org
Issue fields and issue types	repo, public_repo or read:org
Create or change a gist	gist
Notifications and watching	notifications
Read projects	read:project or project
Create or change projects	project
Delete a repository	delete_repo

Pushing changes to workflow files also needs workflow; GitHub refuses those pushes without it. Functions GitHub adds later, and the few with no clear requirement (your own profile, reading gists, organization rulesets and custom properties, the public advisory database), are never greyed. They show the same greyed state, Go to permissions button and refusal message as the other systems. Changing the scopes updates the list straight away. If the connection has no scopes at all, nothing is greyed.

Custom requests#

Custom requests belong to the connection, not to each service: Microsoft Calendar, Mail, Files and the other Microsoft services share one address and one sign-in, so they share one Custom requests function, named for the connection ("Microsoft"). In the open card of a system the platform can call, below How Coworkers use this connection, an Allow custom requests switch is off to start. Turning it on opens a dialog titled "Allow custom requests to" followed by the connection's name, warning that Coworkers will be able to send any request the connected account can make, including requests that change or delete data. Select Allow custom requests to confirm. A function named Custom requests then appears under the switch, and you give it an Allow, Ask or Block default like any other function; it starts on Block. It is always treated as a write, so set it to Ask to review each request, or Block to keep it off. For a GraphQL system such as Linear it sends a query or mutation; for the others it sends a method and a path after the system's address, with optional parameters and a body. The services' own lists show only their ready-made functions. Turning the switch off removes the function. The change is recorded in the audit log as "Changed whether a connector allows custom requests".

How Coworkers use a connection#

For a system the platform can call, the open card shows How Coworkers use this connection with two choices:

Choice	What it means
Functions only	Coworkers act through the functions above and each follows its Allow, Ask or Block. The platform makes the call with the person's access; scripts cannot read the person's sign-in.
Direct access	Scripts can also read each person's sign-in through the environment variable and call the system themselves. Allow, Ask and Block do not apply to those calls.

A connection you add for a listed system the platform can call starts on Functions only. Connections that existed before keep Direct access until you switch them. Choosing Direct access asks you to confirm in a dialog titled "Give Coworkers direct access to" followed by the system's name. Choosing Functions only applies at once, unless the connection has Notes for Coworkers saved: then a dialog titled "Limit Coworkers to" followed by the system's name asks you to confirm, with a tick box Clear the notes for Coworkers (they describe calling the system directly) that is ticked to start. Notes written for calling the system directly no longer fit once Coworkers use functions, so leaving it ticked removes them; untick it to keep them. In Functions only, Coworkers get the function guide plus any notes on the connection. Changes are recorded in the audit log as "Changed how Coworkers reach a connected app".

Some details of how calls are made:

• Calls go only to the system's own address; a Coworker cannot point one at another host.
• Microsoft calendar times use the time zone each person has set under Settings (UTC when none is known). See Your time zone.
• Atlassian and Jira calls need a site. The platform looks it up from the person's account the first time and keeps it. This works with accounts that reach exactly one Atlassian site; for an account that reaches several, the call is refused with a message that an administrator must choose the site, and nothing is run.

Which Coworkers can use it#

Setting a connection up gives no Coworker access to it. A Coworker can read the connection's access token or use its functions only when its own Supervisor has enabled the system for it, and the choice is off until they do. A support Coworker that answers customer email does not get GitHub because you added GitHub.

A Supervisor enables it on the Coworker's details page, under Connectors, where each connected system appears as a card with Enable and Turn off, and how many functions are on. The same person who can enable a connector built by a Coworker can do this; an administrator who does not supervise the Coworker cannot. A Coworker the system is not enabled for gets a plain message that the system is not enabled for it and that its Supervisor can enable it, cannot see the functions when it searches, and cannot read the environment variable. Turning it off applies from the Coworker's next read or call.

Each connection card on the Connectors page shows "Enabled for" and the number of Coworkers. Removing a connection, or a Coworker, removes its enablements.

What people see#

A SharePoint connection that has sign-in with a person's Microsoft account turned on shows up there as one entry named after the connection, not on the Connectors page's list of systems; see Connecting SharePoint.

Everyone who is signed in sees Connected accounts under Settings > My API keys once at least one connection exists. See Connecting your accounts and Approving a request.

When a system refuses the sign-in#

If you cancel on the system's own page, the message reads "You chose not to connect, so nothing was changed." When the system itself turns the sign-in down, the page you started from (for example Connectors) reads "<System> refused the sign-in. Reason:" followed by the system's own error code and description, such as invalid_request with AADSTS50194. Other people see only "<System> refused the sign-in. Ask your administrator to check the connection settings." and no reason. The reason is also written to the server log.

For Microsoft, check first that the Authorize URL and Token URL on the connection use your Directory (tenant) ID in place of common, as in https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/authorize and .../token. An app registered for "My organization only" works only with its own tenant ID; common is for apps registered for multiple organizations or personal accounts. Then check that the redirect URI is registered under Authentication as a Web platform, and that an administrator has approved permissions such as Files.Read.All if your organization requires it.

What policy covers, and what it does not#

Allow, Ask and Block apply to functions called through the connector. Only Coworkers you have enabled the system for can read the token or call the functions. On a connection set to Direct access, a Coworker it is enabled for can read the environment variable in a script and call the system's own API directly, and Allow, Ask and Block do not govern those direct calls. On Functions only every call goes through a function and its policy. Calls that are set to Allow run without an audit entry of their own.

Grant the scopes on your OAuth app with least privilege: only the access you are willing for every enabled Coworker, acting for a connected person, to have.

Changing the scopes does not change what people already connected: they keep the access they were given until they connect again. When you edit the scopes, the form shows how many people need to connect again to get the new access, and each of them sees "Needs new access — connect again" on their account in Settings. If a call fails because the connection lacks a permission (for example reading a private repository), the Coworker is told to ask you to add the permission to the connection; add it here, then ask people to connect again.

A function says the service is not turned on#

When a Coworker reports that a system is connected but its provider has not turned the service on for your organization's app, the API itself is disabled in the provider's developer console. Enable it there and ask the Coworker to try again; people do not need to connect again. For Google, open APIs & Services, then Library, in the Google Cloud project that owns your OAuth app and enable the API (for example Gmail API or Google Calendar API). The server log line connector.rest_failed carries the provider's short reason code as vendor_reason (for example SERVICE_DISABLED).