## Key Takeaways

- **Connecting a tool means handing your AI employee a key to act inside it on your behalf.** There are two kinds of key: a one-click OAuth login, or an API key you paste in.
- **Use OAuth when the tool offers it.** It is faster, you never copy a secret around, and you can revoke access in one click from the tool itself.
- **Use an API key when the tool has no OAuth option, or when you want a service-level connection that is not tied to one person's login.**
- **Most connection failures are not mysterious.** They come from an expired token, a permission scope that was too narrow, or a key pasted with a trailing space. All three are quick fixes.
- **Grant read access first, add write access when you need action.** You can start an integration in read-only mode and widen it later.
- **Viktor connects to 3,200+ tools** and walks you through whichever method a given tool supports, then keeps the connection alive so you are not re-authorizing every week.

## You @mention it to pull a report, and it asks for access

You type one line in Slack: "pull last month's pipeline from HubSpot and compare it to May." Your AI employee replies that it needs access to HubSpot first. Now you are staring at two options you half-recognize: a button that says "Connect with HubSpot," or a field asking for an API key. Pick wrong and you either over-share or hit a wall that says "connection failed."

This is the single most common question new teams ask, by a wide margin. So here is the whole thing in plain English: what connecting a tool actually does, which method to choose, how to do each one, and what to do when a connection stops working.

## What does "connecting a tool" actually mean?

Connecting a tool means giving your AI employee permission to read from and write to that tool on your behalf, the same way you would give a new hire a login on their first day. You are not handing over your password. You are issuing a scoped key that says "this account can see these things and do these actions," and you can take that key back whenever you want.

There are two ways to hand over that key:

- **OAuth** is the "Sign in with Google" pattern. You click a button, the tool shows you exactly what is being requested, you approve, and a token is issued behind the scenes. You never see or copy a secret.
- **An API key** is a long string the tool generates for you. You copy it from the tool's developer settings and paste it into the connection screen. It is more manual, but it works for tools that do not offer a login button.

Both end in the same place: your AI employee can now act in that tool. The difference is how the key gets created and managed.

## OAuth vs API key: which one should you use?

Answer first: if the tool offers a "Connect" or "Sign in" button, use OAuth. Reach for an API key only when there is no button, or when you deliberately want a connection that belongs to the company rather than to one person.

| | OAuth (one-click) | API key (manual) |
|---|---|---|
| **Setup** | Click "Connect," approve the request | Generate a key in the tool, copy, paste |
| **Where the secret lives** | Issued and stored behind the scenes, you never see it | You copy a visible string and paste it |
| **Permissions** | Tool shows the exact scopes before you approve | Often all-or-nothing for that key |
| **Expiry** | Refreshes itself in the background | Stays valid until you rotate or revoke it |
| **Tied to** | The person who approved it | The account that created the key, often a service account |
| **Revoking** | One click inside the tool's connected-apps page | Delete the key in the tool's settings |
| **Best for** | Gmail, HubSpot, Google Drive, Slack, most modern SaaS | Niche tools, internal APIs, service-level access |

The short version: OAuth is cleaner and safer for everyday tools because nobody is emailing a secret around. API keys are the fallback that lets you connect almost anything, including tools the AI employee does not natively support yet.

## How to connect a tool with OAuth (the one-click path)

For most tools you will use, this is the whole flow:

1. Ask your AI employee to use the tool, or open the integrations screen and find it in the list.
2. Click **Connect** next to the tool name.
3. The tool opens its own login page. Sign in with the account you want the AI employee to act as.
4. Read the permission screen. It lists exactly what is being requested, for example "see and send email" or "read and edit your CRM records."
5. Approve. You are returned to the connection screen with the integration now marked active.

A useful habit: connect with the account whose access you actually want. If you sign in to a shared Gmail with your personal login, the AI employee inherits your personal inbox, not the shared one. Pick the right identity at step 3.

## How to connect a tool with an API key (the manual path)

When a tool has no "Connect" button, you connect it with a key:

1. In the tool, open **Settings**, then look for **Developer**, **API**, or **Integrations**.
2. Generate a new API key. Many tools let you name it, so call it something like "Viktor" so you can find it later.
3. Copy the key. Copy the whole thing and nothing extra. A trailing space is the most common reason a freshly pasted key fails.
4. Paste it into the AI employee's connection screen for that tool.
5. If the tool also asks for a domain, account ID, or region, fill those in from the same settings page.

You can do all of this conversationally. For example:

```prompt
I want to connect QuickBooks. Walk me through where to find the API key
and exactly what to paste, step by step.
```

Your AI employee will tell you which settings page to open and which fields it needs, so you are not hunting through documentation.

## Read access vs write access: what to grant

You do not have to grant full control on day one. A good pattern is to start read-only and widen access when you actually need the AI employee to take action.

- **Read access** lets it pull and analyze: last month's ad spend, open deals, recent emails. Low risk, great for the first week while you build trust.
- **Write access** lets it act: draft and send an email, update a deal stage, create a calendar event. Add this once you are comfortable, and keep review-first turned on so it shows you the draft before anything goes out.

If you connected with a scope that was too narrow and the AI employee says it cannot perform an action, you do not start over. You re-run the connection and approve the wider scope, or generate a new key with more permissions.

---

## Why a connection sometimes stops working (and how to fix it)

A connection that worked last week can go quiet. This is normal across every SaaS tool, and it almost always traces to one of three causes:

- **The token expired.** Tools rotate access for security. The fix is to reconnect: click the tool, approve again, done. This takes ten seconds.
- **The scope was too narrow.** You granted read access, now you are asking it to write. Re-authorize and approve the broader permission.
- **The key was rotated or revoked.** Someone regenerated the API key in the tool, which invalidates the old one. Paste the new key.

If you ever see a "connection failed" message, work down that list before assuming anything is broken. Nine times out of ten it is an expired token and a one-click reconnect.

## How Viktor handles connecting tools today

Viktor is an AI employee that lives in Slack and Microsoft Teams and connects to 3,200+ tools. When you ask it to do something that needs a tool it is not connected to yet, it tells you which integration it needs and which method that tool supports, so you are never guessing between OAuth and an API key.

For OAuth tools, it hands you the one-click login. For tools that need a key, it tells you exactly which settings page to open and which fields to fill. Once connected, it keeps the connection alive in the background and prompts you to reconnect only when a token genuinely expires. And because Viktor is review-first by default, write access does not mean surprise actions: it drafts, you approve, then it sends.

If you are wiring up your first integrations, start with the tools you touch daily and add from there. Our guide on [choosing your first 3 integrations](https://viktor.com/blog/choosing-your-first-3-integrations) is a good companion to this one.

## Frequently Asked Questions

### Is OAuth or an API key more secure?

OAuth is generally the safer everyday choice because no human ever copies or stores a secret, and the tool shows you the exact permissions before you approve. API keys are perfectly safe too, as long as you treat the key like a password and rotate it if it leaks. For a deeper look at how this works under the hood, see [MCP vs OAuth](https://viktor.com/blog/mcp-vs-oauth).

### Do I need to be technical to connect a tool?

No. For OAuth tools it is a single button and a login. For API-key tools, your AI employee tells you which settings page to open and what to paste, so the only skill required is copy and paste.

### What does "connection failed" usually mean?

Most often an expired token or a key with a trailing space. Reconnect the tool or re-paste the key cleanly, and check that the account you signed in with actually has access to the data you are asking for.

### Can I connect a tool that is not on the list?

Often yes, through an API key or a generic connector. If a tool exposes an API, there is usually a way to connect it even when it is not a one-click option.

### How do I give my AI employee more permissions later?

Re-run the connection and approve the wider scope, or generate a new API key with more permissions and paste it in. You do not have to disconnect and rebuild from scratch.

### How do I revoke access?

For OAuth, open the connected-apps or third-party-access page inside the tool itself and remove it. For an API key, delete the key in the tool's settings. Either way, access ends immediately.

## Connect your first tool in two minutes

The fastest way to understand the difference between OAuth and an API key is to connect one tool and watch what happens. Pick the app you open most, connect it read-only, and ask your AI employee to pull something you would normally fetch by hand.

[Add Viktor to your workspace, free to start](https://viktor.com/?utm_source=blog&utm_medium=cta&utm_campaign=how-to-connect-any-tool-to-your-ai-employee)

Related reading:

- [Choosing your first 3 integrations for an AI coworker](https://viktor.com/blog/choosing-your-first-3-integrations)
- [MCP vs OAuth: what every business leader gets wrong](https://viktor.com/blog/mcp-vs-oauth)
- [The hidden cost of tool sprawl](https://viktor.com/blog/the-hidden-cost-of-tool-sprawl)