# OAuth connector vs pasting an API key: which to use for each app (/blog/oauth-connector-vs-pasting-an-api-key)

![Illustration: Two front doors side by side: at the left door a small friendly robot with a round camera-eye head rings a doorbell and a human hand opens the door from inside.](/blog/oauth-connector-vs-pasting-an-api-key/hero.webp)

Use OAuth when the connector offers it. You authorize on the provider's consent screen, CoreSpeed stores and refreshes the tokens, and the agent receives tools, never the token. Paste an API key when the connector is key-only, such as Stripe, or when the vendor hands out keys and you want one connection per key. The connector index says which applies.

**OAuth vs a pasted key**

|                       | OAuth connection                                          | Pasted API key                                                         |
| --------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- |
| Who grants access     | you, on the provider's consent screen                     | you, by copying a key from the vendor's dashboard                      |
| Refresh               | ✓ automatic, where the provider allows                    | none; the key lives until the vendor revokes it                        |
| Rotation              | reauthorize in the dashboard                              | paste the new key; the connection updates in place                     |
| Disconnect            | removes the connection                                    | deletes CoreSpeed's copy; the key still works at the vendor            |
| Reaches needs\_reauth | failed refresh, invalid credential, or a replaced org app | only when the vendor names the credential invalid with a standard code |
| Visibility            | private or shared                                         | private or shared                                                      |

With OAuth the grant is the connection. With a key, the connection is a copy of something you still own.

## How do you tell which method a connector uses? \[#how-do-you-tell-which-method-a-connector-uses]

The authenticated index is the only inventory. It returns what this caller can connect and the state of every account already connected:

```bash
curl https://api.corespeed.io/connectors \
  -H "Authorization: Bearer $CORESPEED_API_KEY"
```

Three fields answer the question. A key-only connector carries `auth.type: "api_key"`. An OAuth connector that also accepts a key carries `auth.api_key_connect: true`, and the dashboard shows the two methods side by side. A handful of connectors use OAuth 1.0a, such as Trello and Zotero, marked `auth.type: "oauth1a"`; the experience is the same as OAuth.

Two more fields describe a key connection after it is made. Where the vendor lets CoreSpeed verify the key at paste time, it is verified. Where the vendor does not, the connection is stored unverified and the index marks it `api_key_probe: false` and `key_verified: false`. The [connectors page](/docs/connectors) documents the full shape.

## What happens with an OAuth connection? \[#what-happens-with-an-oauth-connection]

The member opens Dashboard → Connectors, clicks Connect, reviews the requested scopes on the provider's consent screen, and authorizes. The consent screen names CoreSpeed, because the OAuth client is CoreSpeed's. The access and refresh tokens stay inside the organization boundary, and CoreSpeed refreshes them on its own where the provider allows.

The connection is private, usable by the member who connected it and their clients, or shared with the whole organization. An agent principal reaches shared ones only. Tools appear in `tools/list` as `notion__create_page`, `slack__post_message` and so on, and no provider id or token ever needs to appear in a prompt.

An OAuth connection reaches `needs_reauth` when a refresh fails, when the vendor names the credential as invalid, or when an organization's own OAuth app is replaced or deleted. The tools stay visible; calls fail until the member reauthorizes in the dashboard. Rotating the CoreSpeed key or rewriting client config helps nothing, because neither is broken.

## What happens with a pasted key? \[#what-happens-with-a-pasted-key]

A pasted key is stored encrypted as a connection: one row, with the same private-or-shared visibility as any OAuth account. Rotation is a reconnect. Paste the new key and the connection updates in place, with the same alias and the same tools.

Disconnecting deletes CoreSpeed's copy and nothing more. The key itself keeps working until you revoke it in the vendor's dashboard. This is the biggest difference in day-to-day handling: with OAuth, the grant is the connection; with a key, the connection is a copy of something you still own elsewhere.

A rejected call does not change a key connection's status. A vendor `401` flips it to `needs_reauth` only when the vendor names the credential itself with a standard code, `invalid_token`, `invalid_client` or `invalid_grant`, rather than CoreSpeed guessing from a failed request. Recovery is the same move as rotation: paste a new key.

| Concern                | OAuth                                                     | Pasted API key                                               |
| ---------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| Who grants access      | You, on the provider's consent screen                     | You, by copying a key from the vendor's dashboard            |
| Refresh                | Automatic, where the provider allows                      | None; the key lives until the vendor revokes it              |
| Rotation               | Reauthorize in the dashboard                              | Paste the new key; the connection updates in place           |
| Verified at connect    | By the provider's own flow                                | Some vendors verify; otherwise `key_verified: false`         |
| Disconnect             | Removes the connection from CoreSpeed                     | Deletes CoreSpeed's copy; the key still works at the vendor  |
| Reaches `needs_reauth` | Failed refresh, invalid credential, or a replaced org app | The vendor names the credential invalid with a standard code |
| Visibility             | Private or shared                                         | Private or shared                                            |

## When should you choose each? \[#when-should-you-choose-each]

Choose OAuth whenever it is offered. It is the default for a reason: scopes are reviewed on screen, refresh is automatic, and revoking is a disconnect. It is also the only route for organization integrations, where the vendor installs CoreSpeed's app as its own actor, such as Slack's workspace bot and Linear's app under the alias `corespeed-bot`. Only an org admin connects one of those.

Choose a pasted key when the connector is key-only, when the vendor issues keys for the account you want the agent to act through, or when you already manage that key in the vendor's dashboard and want it behind the connection as is. Treat the key's lifecycle as yours: CoreSpeed holds a copy, and revocation happens at the vendor.

A third route exists for vendors whose review process gates a shared OAuth app, such as Google, Microsoft and Meta. An org admin registers the organization's own OAuth app by pasting its `client_id` and `client_secret`, and every new connection in the organization authorizes through it. Calls through your own app are not metered by CoreSpeed; holds and the activity trail still apply.

Whichever route you pick, the ending is the same. The agent sees tools in `tools/list`. Several accounts on one connector each get an alias, renamable with `manage__accounts_rename`, and a call with more than one in scope and no `account` argument answers `ambiguous_account` with the aliases to choose from. A failing call is diagnosed the same way too: the [error handling page](/docs/errors) applies to both.

## FAQ \[#faq]

**Can one app have both an OAuth account and a key connection?**
Yes, where the index shows `auth.api_key_connect: true`. Each becomes its own account with its own alias.

**Does the agent ever see the pasted key?**
No. The key is stored encrypted and the agent receives tools. The same custody rule applies to OAuth tokens.

**If I disconnect a key connection, is the key dead?**
No. Disconnect deletes CoreSpeed's copy only. Revoke the key in the vendor's dashboard if you want it gone.

**Why is a key connection marked `key_verified: false`?**
The vendor offers no way to probe the key at paste time. The connection is stored and the first real call tells you whether it works.

**Who can remove a shared connection?**
Whoever connected it, or an org admin. The index reports the rule per account as `can_remove`, so a client does not have to guess.