Authentication

VelaFlows uses API tokens with workspace-scoped access for all API requests. Every request must include an Authorization header with your token and an x-workspace-id header to identify which workspace you’re operating in.

Creating an API Token

1. Log in to app.velaflows.com 
2. Navigate to Settings > Developer > API Tokens
3. Click Create Token
4. Give your token a descriptive name (e.g., “Production API”, “Zapier Integration”)
5. Select the scopes your token needs (see Scopes below)
6. Click Create
7. Copy your token immediately — it will only be shown once

Your token looks like this:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

The first 16 characters (sk_live_a1b2c3d4) are the visible prefix, shown in the dashboard so you can identify tokens. The rest is the secret portion.

Using Your Token

Include two headers on every API request:

Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
x-workspace-id: 64f1a2b3c4d5e6f7a8b9c0d1

Example Request

curl -X GET https://api.velaflows.com/api/v1/inbox/conversations \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8..." \
  -H "x-workspace-id: 64f1a2b3c4d5e6f7a8b9c0d1"

Token Format

Both token types are 48+ characters long. The prefix tells you which environment the token operates against.

Finding Your Workspace ID

Your workspace ID is a 24-character MongoDB ObjectId. You can find it in several places:

1. Dashboard URL — It appears in the URL when you’re logged in: app.velaflows.com/dashboard/...
2. Settings > General — Displayed on the workspace settings page
3. API Response — Returned when you list your workspaces via the auth API

Scopes

API tokens use granular scopes to control access. When creating a token, select only the scopes your integration needs. This follows the principle of least privilege.

Available Scopes

Scope Examples

A read-only dashboard integration might use:

inbox:read, crm:read, contacts:read, analytics:read

A chatbot that replies to messages might use:

inbox:read, inbox:write, channels:read, channels:write, ai:read

A CRM sync integration might use:

crm:read, crm:create, crm:update, contacts:read, contacts:write

Token Lifecycle

Active Tokens

Tokens are active from the moment they’re created. They remain valid until explicitly revoked or until they reach their expiration date (if one was set).

Revoking Tokens

To revoke a token:

1. Go to Settings > Developer > API Tokens
2. Find the token in the list (identified by name and prefix)
3. Click the Revoke button
4. Confirm the action

Revoked tokens are immediately invalidated. Any API request using a revoked token will receive a 401 Unauthorized response.

Token Expiration

When creating a token, you can optionally set an expiration date. Expired tokens are automatically invalidated and cannot be used. You’ll need to create a new token to replace an expired one.

Regeneration

There is no way to regenerate or view a token after creation. If you lose your token, revoke it and create a new one.

Security Best Practices

Never commit tokens to source control

Use environment variables instead:

# .env (add to .gitignore)
VELAFLOWS_API_TOKEN=sk_live_a1b2c3d4e5f6g7h8...
VELAFLOWS_WORKSPACE_ID=64f1a2b3c4d5e6f7a8b9c0d1

// In your code
const token = process.env.VELAFLOWS_API_TOKEN
const workspaceId = process.env.VELAFLOWS_WORKSPACE_ID

Use the minimum required scopes

Only grant the permissions your integration actually needs. A webhook listener that only reads conversations shouldn’t have admin:all access.

Rotate tokens regularly

Create new tokens and revoke old ones on a regular schedule (e.g., every 90 days). This limits the blast radius if a token is compromised.

Use separate tokens per integration

Don’t share a single token across multiple integrations. If one integration is compromised, you can revoke its token without disrupting others.

Monitor token usage

Review your active tokens periodically in the dashboard. Revoke any tokens that are no longer in use.

Error Responses