Choose between OAuth connection and Client credentials

Pick the authentication method for your Vibe app based on how your customers will connect their Vibe account to your product.

When you create an app in the Vibe Developer tool, you choose one of two authentication methods:

  • OAuth connection: uses the OAuth 2.0 authorization_code grant.
  • Client credentials: uses the OAuth 2.0 client_credentials grant.

Both methods return a short-lived Bearer access token that you send on every API call. What differs is how each customer grants your app access, and what you build, store, and maintain as a result.

⚠️

You cannot change the method after you create the app

The authentication method is fixed at app creation. If you pick the wrong one, you must create a new app. Make the choice before you build.


Start with one question

How will your customers connect their Vibe account to your product?

Your answerMethod
They sign in with their Vibe account. They click "Connect with Vibe" in your product and approve access.OAuth connection (authorization_code), best to distribute
They paste their own credentials into your product. Each customer creates a client ID and secret in Vibe and enters them in your product. You keep one pair per customer.Client credentials (client_credentials)
It's just for your account. The app only works on your own Vibe account and won't be distributed. You use the credentials you get when you create it.Client credentials (client_credentials), best for your account

Detailed comparison

OAuth connection (authorization_code)Client credentials (client_credentials)
How customers connectSign in with Vibe and approve accessCreate a client ID and secret in Vibe and paste them into your product
Customer effortOne click and a sign-inCreate credentials in Vibe, then copy them into your product
What you storeAccess and refresh tokens per customerClient ID and secret per customer, plus the access tokens you get from them
What you manageRequesting new tokens using refresh tokens, and handling customers who revoke accessRequesting new tokens with the stored credentials, and updating credentials when customers rotate them
What you buildAn OAuth 2.0 client implementationA settings page where customers enter their credentials
Token lifetimeAccess token: 30 minutes. Refresh token: 90 days, replaced on every refresh.Access token: 30 minutes. No refresh token: request a new access token with the client ID and secret.
Best forApps you plan to distributeApps for your own account only, or products that already collect customer credentials

Which one should you pick?

Pick OAuth connection to distribute your app

Choose OAuth connection for any app that other Vibe customers connect their account to. Customers have no credentials to create, copy, or rotate. It is also required for embedded partners.

Pick Client credentials for your own account

Choose Client credentials when the app only serves you, on your own Vibe account. It is the simplest option: no redirect, no consent screen, no refresh tokens. Your server exchanges the client ID and secret for an access token whenever it needs one.

Also choose it when your product already collects customer credentials and cannot, or will not, host an OAuth redirect. In that case, each customer installs your app from the Marketplace, receives their own client ID and secret, and enters them in your product. Each credential pair is bound to the Vibe account where the app was installed.

Don't choose based on "user present" vs "server-to-server"

An OAuth connection also runs unattended. After the customer approves access once, your backend keeps calling the API on their behalf with refresh tokens, so nightly syncs, report exports, and other background jobs work the same way. What matters is how each customer grants access, not whether someone is in front of a screen when your code runs.


Both methods start private

Every app starts private and works only on your own Vibe account, whichever method you choose. Before any other customer can connect to it, you must make the app public and get it approved through Vibe's review (typically 5-10 business days).

Best practice: build and test privately, prove the integration works end-to-end, then submit it. See Submit your app for review and Marketplace listing.


Client credentials are not legacy API keys

Before the Developer Platform, Vibe reporting was called with a per-account key sent in an X-API-Key header. That legacy mechanism is being decommissioned and is unrelated to Client credentials:

  • Client credentials issue a client ID and secret for the OAuth 2.0 client_credentials grant, which returns Bearer tokens.
  • Legacy API keys are sent as-is in the X-API-Key header and do not use OAuth.

If you still send X-API-Key, migrate to a Bearer token from either method. Choose the method with the question above, exactly as for a new app. See Migration Guide from API Key.


Next steps


Did this page help you?