OAuth connector vs pasting an API key: which to use for each app

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

Aspect	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

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:

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 documents the full shape.

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?

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?

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 applies to both.

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.