Authenticate with OAuth 2.0 Authorization Code

Creating an App

1. In the Vibe Developer tool, create an app and select OAuth as the authentication method.
2. Register every redirect URI your app uses. Each URI must exactly match the redirect_uri in your authorization requests; register separate development and production URIs when needed.
3. Select only the grant types and scopes your integration requires.
4. After app creation, copy the client_id and client_secret. Store the secret only on your server; it is required for the token exchanges below.

For Marketplace requirements—including app information, required listing content, support materials, scope review, and submission—see Submit your app for review and Marketplace listing.

Base URL

All OAuth endpoints are available at:

https://api.vibe.co

Authorization Code Flow

Use this flow when your application needs access to resources owned by a specific Vibe user. The user is redirected to Vibe to authenticate and approve access, then returned to your app with an authorization code you exchange for a token.

Step 1 — Generate state and a PKCE pair

Before each authorization request, generate three new values:

• state: an opaque, cryptographically random value that protects against CSRF. You will verify it on the callback in Step 3.
• code_verifier: a cryptographically random string of 43 to 128 characters from A-Z, a-z, 0-9, -, ., _, ~.
• code_challenge: BASE64URL(SHA256(code_verifier)), without = padding.

import crypto from 'node:crypto';

const state = crypto.randomBytes(16).toString('base64url');
const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');

import base64
import hashlib
import secrets

state = secrets.token_urlsafe(16)
code_verifier = secrets.token_urlsafe(32)
code_challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode("ascii")).digest())
    .rstrip(b"=")
    .decode("ascii")
)

Store state and code_verifier server-side, tied to the user's session. You will send state and code_challenge in Step 2, verify state in Step 3, and send code_verifier in Step 4.

Never reuse these values across authorization requests, and never send the code_verifier in the authorization request.

Step 2 — Redirect the user to Vibe

Send the user to the Vibe authorization endpoint with the following query parameters:

GET https://api.vibe.co/oauth2/auth

Example redirect URL:

https://api.vibe.co/oauth2/auth?client_id=<YOUR_CLIENT_ID>&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=campaigns%3Aread&state=abc123xyz&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Step 3 — Handle the callback

After the user authorizes your app, Vibe redirects them to your redirect_uri with two query parameters:

GET https://yourapp.com/callback?code=<AUTHORIZATION_CODE>&state=<YOUR_STATE>

Before proceeding, verify that state matches the value you stored in Step 1. If it does not match, reject the request.

If the user denies access or an error occurs, the redirect will include error and error_description parameters instead:

GET https://yourapp.com/callback?error=access_denied&error_description=The+user+denied+access

Step 4 — Exchange the code for a token

Make a server-side POST request to exchange the authorization code for an access token. Never make this request from client-side code, as it requires your client secret.

POST https://api.vibe.co/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <BASE64(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)>

grant_type=authorization_code
&code=<AUTHORIZATION_CODE>
&redirect_uri=https://yourapp.com/callback
&code_verifier=<YOUR_CODE_VERIFIER>

The Authorization header value is Basic followed by the Base64 encoding of <client_id>:<client_secret>.

code_verifier is the original value you generated in Step 1, before hashing. If it does not match the code_challenge sent in Step 2, the request fails with invalid_grant.

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "ory_rt_...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Store the refresh_token securely. You will use it to obtain new access tokens without requiring the user to re-authorize. The access token expires after 30 minutes.

Step 5 — Call the API

Include the access token as a Bearer token in the Authorization header of every API request:

GET https://api.vibe.co/*
Authorization: Bearer <ACCESS_TOKEN>

Token Response Reference

Access tokens are JWTs. You can inspect the payload by Base64-decoding the middle segment (between the two . characters). The payload contains standard claims such as sub, scope, iat, and exp. Do not rely on the token payload structure in your integration logic — use the API responses instead.

Tokens expire after the duration indicated by expires_in. Use the refresh_token from the Authorization Code flow to obtain a new access token without user interaction. The Client Credentials flow does not issue refresh tokens.

Refreshing Access Tokens

When an access token expires, use the refresh token to obtain a new one without requiring the user to re-authorize. This only applies to the Authorization Code flow — Client Credentials tokens cannot be refreshed.

POST https://api.vibe.co/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <BASE64(YOUR_CLIENT_ID:YOUR_CLIENT_SECRET)>

grant_type=refresh_token
&refresh_token=<YOUR_REFRESH_TOKEN>

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "ory_rt_...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Each refresh issues a new refresh token. Replace the stored refresh token with the one returned in the response — the previous token is invalidated.

Error Reference

Errors from the authorization endpoint and token endpoint follow OAuth 2.0 standard error codes.

Error responses from the token endpoint are JSON:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}