Connecting a service

Everything here is stored in your operating system keyring — Keychain on macOS, DPAPI on Windows, libsecret on Linux — and brokered by Studio, so an automation never holds a credential. Connect once in Settings → Connections and every automation on the machine can use it.

Nothing here is a Claritty account. Where a service needs an OAuth app — Gmail, Jira, WhatsApp — you create your own. There is no Claritty client id to sign into, which is the point: your automations talk to your accounts.

The 13 you can connect

Airtable

Create a personal access token at https://airtable.com/create/tokens with the data.records:read and data.records:write scopes, and grant it access to the base.

Tools an automation can call: airtable.list_records, airtable.create_record

Brave Search

Create a free key at https://api-dashboard.search.brave.com/ (the free tier allows 2,000 queries a month).

Tools an automation can call: brave-search.web

GitHub

Create a fine-grained personal access token at https://github.com/settings/tokens with access to the repositories this automation should touch.

Tools an automation can call: github.list_issues, github.create_issue, github.comment

Gmail

Gmail needs YOUR OWN Google app — Studio never uses a Claritty one, so nothing here depends on an app we control. At https://console.cloud.google.com/apis/credentials create an OAuth client (type: Desktop app), enable the Gmail API, and add the https://www.googleapis.com/auth/gmail.modify scope. Then get a refresh token for it — https://developers.google.com/oauthplayground with "Use your own OAuth credentials" ticked is the quickest way. Paste the client id, client secret and refresh token below; the access token is derived and never stored.

Tools an automation can call: gmail.send, gmail.search, gmail.get_message

Jira

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens, then give your site (the yourcompany.atlassian.net part, no https://), the email you sign in with, and that token. Jira Cloud authenticates the pair as HTTP basic — there is no OAuth app to register and no admin needed.

Tools an automation can call: jira.create_issue, jira.search_jql, jira.add_comment

Linear

Create a personal API key in Linear under Settings → Security & access → Personal API keys.

Tools an automation can call: linear.create_issue

Notion

Create an integration at https://www.notion.so/my-integrations, copy the Internal Integration Secret, then share the target page or database with it from Notion’s ⋯ menu — otherwise it sees nothing.

Tools an automation can call: notion.create_page, notion.query_database

Outbound webhook

No credential needed. Give the automation a URL and it will POST JSON to it — useful for Zapier, Make, n8n, or anything you already run.

Tools an automation can call: outbound-webhook.post

Email (Resend)

Create an API key at https://resend.com/api-keys and verify the domain you want to send from. The free tier covers a few thousand emails a month, which is more than an automation needs.

Tools an automation can call: resend.send

Slack

Create an app at https://api.slack.com/apps, add the chat:write scope under OAuth & Permissions, install it to your workspace, and copy the Bot User OAuth Token. Invite the bot to any channel it should post in. To let it RECEIVE instructions too: turn on Socket Mode, subscribe to the app_mention event, and generate an app-level token with connections:write. Studio dials out to Slack, so nothing needs a public URL and there is no webhook to expose.

Tools an automation can call: slack.post_message

Stripe

Copy a restricted key from https://dashboard.stripe.com/apikeys. Give it read access only unless the automation genuinely needs to move money.

Tools an automation can call: stripe.list_invoices

Telegram

Message @BotFather in Telegram, send /newbot, and copy the token it gives you. Then message your new bot once and open https://api.telegram.org/bot<TOKEN>/getUpdates to find your chat id.

Tools an automation can call: telegram.send_message

WhatsApp

WhatsApp needs YOUR OWN Meta app — Studio never brokers this. At https://developers.facebook.com create an app, add the WhatsApp product, and from its API Setup page copy the phone number id and a permanent access token (generate one from a System User in Business Settings; the sample token shown there expires in 24 hours). Message your own number from that page once, so WhatsApp will let the number receive messages back.

Tools an automation can call: whatsapp.send_message

The other 27, which Studio cannot broker yet

The hosted platform provides these. Studio has no connector for them, so an automation that calls one fails at run time, however sensible the id looks.

They are listed in full rather than hidden, for two reasons. Every tool id below is real, so knowing the exact name is most of the work of adding it. And a name you can see is a name nobody has to guess: the expensive failure here is an agent inventing jira.create_issue because the shape of the id was obvious.

Accounting

AI

Analytics

Calendar

Communication

CRM

Developer tools

Email

Files

Marketing

Productivity

Social

Adding a connector for one of the 27

This is a defined job rather than a wish, and it takes an afternoon. A connector is declarative: no code runs per service, so what you are writing is a spec the engine executes.

1. Write the request

From inside an automation, ask your coding agent for the add-an-integration skill. It produces INTEGRATION-REQUEST.md: where a person gets the credential, the fields, the auth type, and one block per operation you actually need. A connector with three used tools beats one with thirty untested ones.

Do this rather than reaching for the closest-looking tool id. A manifest naming a tool nothing implements passes validation, runs, gets skipped, and reports success, which is the worst way for an automation to fail.

2. Pick the auth type

One of the engine's, and which field carries it:

If the provider only accepts a value in the URL, as Telegram does with the bot token and WhatsApp with the phone number id, name those fields in pathCredentials on the tool. That is opt-in on purpose, and every named value is scrubbed out of anything the call throws.

3. Add the spec

It goes in packages/connectors/src/catalog.ts. This is Slack, whole:

{
  id: "slack",
  name: "Slack",
  howToConnect: "Create an app at https://api.slack.com/apps, add the chat:write scope under OAuth & Permissions, install it to your workspace, and copy the Bot User OAuth Token. Invite the bot to any channel it should post in. To let it RECEIVE instructions too: turn on Socket Mode, subscribe to the app_mention event, and generate an app-level token with connections:write. Studio dials out to Slack, so nothing needs a public URL and there is no webhook to expose.",
  fields: [
    {
      key: "bot_token",
      label: "Bot user OAuth token",
      secret: true,
      placeholder: "xoxb-…"
    },
    {
      key: "app_token",
      label: "App-level token (optional, to receive messages)",
      secret: true,
      placeholder: "xapp-…",
      optional: true
    }
  ],
  tools: [
    {
      id: "slack.post_message",
      summary: "Post a message to a channel.",
      method: "POST",
      url: "https://slack.com/api/chat.postMessage",
      auth: {
        type: "bearer",
        field: "bot_token"
      },
      body: {
        channel: "{arg.channel}",
        text: "{arg.text}",
        thread_ts: "{arg.thread_ts}"
      },
      result: "ts"
    }
  ]
}

{arg.x} is an argument from the automation. A body value that is exactly {arg.x} keeps its type; "{arg.x} items" makes it a string. result is a dotted path into the response, or omit it to return the whole body.

4. The rules the engine enforces

• A credential may not appear in a URL unless the spec names it in pathCredentials. {creds.*} in a url or query is rejected outright, because those leak into logs, error messages and run history. Use auth.
• Public hosts only. No localhost, link-local or private ranges. An automation that takes a URL as input must not become a way to reach your router or a cloud metadata endpoint.

5. Prove it, then regenerate

pnpm test                 # the engine, including your spec
pnpm proof:integrations   # a real HTTP call through the vault, credential never leaving the host
pnpm sync:catalog         # this page, the seed catalog and llms.txt

That last command is what moves the service out of the table above and into the list at the top, everywhere it is named, including on claritty.ai. Nothing about a connector is written by hand twice.