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_codegrant. - Client credentials: uses the OAuth 2.0
client_credentialsgrant.
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 appThe 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 answer | Method |
|---|---|
| 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 connect | Sign in with Vibe and approve access | Create a client ID and secret in Vibe and paste them into your product |
| Customer effort | One click and a sign-in | Create credentials in Vibe, then copy them into your product |
| What you store | Access and refresh tokens per customer | Client ID and secret per customer, plus the access tokens you get from them |
| What you manage | Requesting new tokens using refresh tokens, and handling customers who revoke access | Requesting new tokens with the stored credentials, and updating credentials when customers rotate them |
| What you build | An OAuth 2.0 client implementation | A settings page where customers enter their credentials |
| Token lifetime | Access 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 for | Apps you plan to distribute | Apps 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_credentialsgrant, which returns Bearer tokens. - Legacy API keys are sent as-is in the
X-API-Keyheader 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
- Authenticate with OAuth 2.0 Authorization Code: set up an OAuth connection app and implement the flow.
- Authenticate with Client Credentials: set up a Client credentials app and request tokens.
- Required headers: headers every API request needs, including
X-Vibe-Revision.
Updated 25 days ago