Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The Vendaze API uses OAuth 2.1 Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the same standard used by HubSpot and Pipedrive for third-party integrations.

Register your app first

You need a client_id and client_secret before continuing.

​
How it works

1. Generate PKCE pair     code_verifier + code_challenge
2. Redirect the user      GET /oauth/authorize
3. User logs in           selects workspace, approves scopes
4. Receive auth code      your redirect_uri?code=...&state=...
5. Exchange for tokens    POST /oauth/token
6. Make API calls         Authorization: Bearer {access_token}
7. Refresh when expired   POST /oauth/token (grant_type=refresh_token)

​
Step 1 - Generate PKCE values

PKCE prevents authorization code interception attacks. Generate these on your server before redirecting: 
// Node.js example
const crypto = require('crypto');

const codeVerifier = crypto.randomBytes(32).toString('base64url');

const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
Store the code_verifier server-side. You will need it in Step 5.

​
Step 2 - Redirect the user

Build the authorization URL and redirect the user’s browser to it: 
GET https://api.vendaze.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/oauth/callback
  &response_type=code
  &scope=people:read deals:write
  &state=RANDOM_CSRF_TOKEN
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
ParameterRequiredDescription
client_idYesYour app’s client ID.
redirect_uriYesMust exactly match a registered URI.
response_typeYesMust be code.
scopeYesSpace-separated scopes.
stateYesRandom string you generate. Returned unchanged. Used to prevent CSRF.
code_challengeYesBASE64URL(SHA256(code_verifier))
code_challenge_methodYesMust be S256.
Always verify that the state parameter in the callback matches what you sent. Reject the request if they do not match. It is a CSRF protection mechanism.

​
Step 3 - User authorizes

The user is redirected to Vendaze, where they:
  1. Log in (if not already logged in)
  2. Select which workspace to connect to your app
  3. Review and approve the requested scopes
  4. Click “Authorize”

​
Step 4 - Handle the callback

After approval, the user is redirected to your redirect_uri: 
https://yourapp.com/oauth/callback?code=AUTH_CODE&state=YOUR_STATE
Verify state matches, then proceed to exchange the code. If the user denies authorization: 
https://yourapp.com/oauth/callback?error=access_denied&state=YOUR_STATE

​
Step 5 - Exchange code for tokens

Authorization codes expire in 5 minutes and can only be used once. Exchange immediately after receiving the callback.
curl -X POST https://api.vendaze.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://yourapp.com/oauth/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code_verifier": "YOUR_ORIGINAL_CODE_VERIFIER"
  }'
Response (200): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "workspace_slug": "acme-corp"
}
FieldDescription
access_tokenUse this in every API request. Expires in 1 hour.
refresh_tokenUse this to get a new access token. Valid for 60 days if used regularly.
token_typeAlways Bearer.
expires_inSeconds until the access token expires.
workspace_slugSlug of the workspace the user authorized. Use this to identify the connected account in your app.
Store both tokens securely on your server. Never expose them in client-side code or URLs.

​
Step 6 - Make API calls

Include the access_token in every request as a Bearer token: 
curl https://api.vendaze.com/v1/people \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Step 7 - Refresh the access token

Access tokens expire after 1 hour. Refresh them using the refresh token: 
curl -X POST https://api.vendaze.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
The response is identical to Step 5. Replace both tokens on your side. A new refresh token is issued on every refresh.
Refresh tokens expire if unused for 60 days. Each time you use a refresh token, the 60-day window resets. If a refresh token expires, the user must go through the full authorization flow again.

​
Revoking access

To disconnect a workspace from your app: 
curl -X POST https://api.vendaze.com/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ACCESS_OR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
Returns 200 regardless of whether the token was already revoked or expired (idempotent).

Make your first request

Use your access token to make a real API call.