Back to all posts
Backend7 min read·October 25, 2026

API Keys vs OAuth: Which Does Your Integration Need?

TB
ThynkBlox Team
Engineering

An API key commonly identifies the calling application or account, while OAuth provides a framework for granting an application access with defined permissions. For an integration accessing customer-owned data, use the provider's supported delegation flow, often OAuth. For access under your own service account, an API key may fit if the provider supports it. These mechanisms solve different access problems; neither is a drop-in replacement for the other.

What does an API key actually represent?

An API key is a credential issued by an API provider. Its meaning depends on that provider: it might identify a project, an account or an application, and it may also authorise requests. Some keys have restricted permissions; others grant broad account access. Do not assume every API key has the same capabilities.

For a founder, the useful question is: whose authority does this key carry?

If your business connects its own reporting service to its own account, a key may express that relationship adequately. If customers must copy account keys into your product, examine whether those keys grant more access than your feature needs.

A key alone does not define a user consent journey. Your product still needs to explain what connecting an account permits.

What does OAuth add to an integration?

OAuth separates the application requesting access from the party authorising it. In a customer connection flow, the customer is directed to the provider, where access can be approved under the provider's rules. Your application receives tokens for the approved access instead of collecting the customer's provider password.

This supports a clearer product experience: connect an account, explain the requested access, show connection status, and provide a way to disconnect.

OAuth is an authorisation framework. An access token is not, by itself, proof that someone has signed into your product. If you also need sign-in, treat that as a separate requirement and use an appropriate identity protocol.

How should you compare API keys and OAuth?

Start with ownership and permissions, then consider implementation effort.

Decision questionAPI keyOAuth
What does access commonly represent?An application, project or accountA grant of access to an application
How is access approved?A key is issued and supplied under provider rulesAn authorisation flow establishes the grant
Can permissions be limited?Depends on the provider's key modelScopes can describe requested access
How does continued access work?Depends on key expiry and rotation rulesAccess tokens expire; refresh may be available
How does access end?Disable, delete or expire the key as supportedRevoke the grant or tokens as supported

Do not choose solely because one looks quicker to build. Ask the build partner to describe the connection's full life: approval, normal use, permission changes, failure and removal.

How should consent and scopes work?

Consent should explain the business action the customer is allowing. “Read your invoices to prepare reports” is clearer than “Enable account access”.

OAuth scopes are permission identifiers defined by the provider. They can distinguish operations such as reading records and changing them, but their precision varies. A scope may cover more than your feature uses.

Request the smallest permission set that supports the feature. If a later feature needs additional access, explain that change before asking the customer to approve it.

Approval also has boundaries. Connecting an account does not necessarily mean every member of your customer's workspace should see its data. Define who can connect accounts, who can use each connection, and who can remove it.

What happens when an access token expires?

OAuth access tokens have a limited lifetime. Some flows also issue a refresh token, which lets the application request a replacement access token without repeating the customer's authorisation interaction. Refresh tokens are not guaranteed in every flow or provider configuration.

An expired access token should trigger the supported renewal process. A rejected refresh attempt needs a different response: pause affected work and tell an authorised customer that reconnection is required.

Ask the implementation team to handle these cases explicitly:

  • A scheduled job starts after the access token expires.
  • Several jobs try to renew the same connection together.
  • Renewal returns a replacement refresh token.
  • The provider rejects further access.
  • Reconnection succeeds after queued work has accumulated.

These are acceptance criteria for the integration. Specify whether delayed jobs resume automatically and how customers can review what remains unfinished.

What should revocation and disconnect do?

Revocation means withdrawing access. Providers may support revoking tokens, an authorisation grant or API keys, with different effects and timing. Do not promise that every credential becomes unusable immediately unless the provider documents that behaviour.

Define your own disconnect behaviour precisely. A useful requirement is: stop scheduling new work, prevent queued work from starting, remove locally stored credentials, and invoke the provider's revocation mechanism where supported.

Also decide what happens to previously imported data. Removing access and deleting stored business records are separate product decisions. Explain both so customers know what the disconnect button does.

Where should credentials be stored?

For a typical web integration with a backend, keep secret API keys, client secrets and refresh tokens on the server. Do not embed them in browser code or mobile application packages. Some API keys are explicitly designed to be public identifiers, so follow the provider's classification rather than treating every key alike.

Require controlled access to stored credentials, encryption at rest, protected transport and removal of credentials from logs. Treat bearer access tokens as sensitive: possession can permit their use within the token's authority.

Server-side storage also needs customer isolation. Each connection should belong to a specific customer account, and every job should check that relationship before using it. For broader context, see data security in modern applications.

What would this look like in a real product?

Consider an illustrative reporting product that imports invoices.

For the operator's own account, the provider might offer a restricted API key. The operator creates that key, stores it on the server and defines a replacement process.

For customer-owned accounts, suppose the provider offers OAuth. A customer chooses “Connect”, approves invoice-reading access with the provider, and returns to the reporting product. The product stores the connection against that customer's workspace and imports only the records required.

The acceptance checklist should cover:

  • Only authorised workspace members can create or remove connections.
  • Requested permissions match the reporting feature.
  • Expired access renews through the supported flow.
  • Lost authorisation produces a clear reconnect message.
  • Disconnect stops future imports.
  • Imported data follows a stated retention policy.
  • Credentials and sensitive responses stay out of logs.

These checks belong in the delivery plan; software testing and quality assurance provides related context.

What common mistakes should you avoid?

Calling OAuth automatically secure. It still requires correct implementation and credential protection.

Treating API keys as necessarily unrestricted. Review the actual provider's permission controls before deciding.

Requesting write access for a read-only feature. Make permission requests traceable to a customer action.

Retrying every failure indefinitely. Define when work pauses and when a customer needs to reconnect.

Assuming this is always a customer consent decision. Some OAuth flows support application access without an interactive user consent screen. Private services may also use other authentication methods. Start with the provider's supported model and your access requirements.

What are the frequently asked questions?

Is OAuth always better than an API key?

No. Choose according to whose resources are involved, the permissions required and the provider's supported methods. A suitable restricted key can serve an operator-owned connection; customer delegation may call for OAuth.

Does every OAuth integration need refresh tokens?

No. Availability depends on the flow and provider. Establish how long the integration must run unattended, then confirm the supported renewal behaviour.

Can we start with API keys and switch later?

Possibly, but plan for customers to reconnect. Credential storage, permission handling and background jobs may need changes. Treat the switch as an access migration with clear acceptance criteria.

What should we ask a development partner?

Ask them to demonstrate approval, permission limits, renewal, lost access and disconnect. A successful first request proves only one part of the integration.


*Planning an integration? Discuss the access and connection requirements →*

Ready to build?

Let's turn these ideas into your next product.

Start your project