Authentication¶

Vellocity supports multiple authentication methods depending on the API domain and integration type.

Authentication Methods¶

Method	Used By	Header Format
API Key (Bearer token)	Partner API, all `/api/v1` endpoints	`Authorization: Bearer YOUR_API_KEY`
OAuth 2.1 (Passport)	MCP Server, user-facing endpoints	`Authorization: Bearer OAUTH_TOKEN`
Token URL	GTM Schedule ICS feeds	`?token=FEED_TOKEN` (query parameter)

API Key Authentication¶

Most API endpoints use Bearer token authentication.

Getting Your API Key¶

Navigate to Settings > API Keys in your dashboard
Click Generate New Key
Copy and securely store the key — it is shown only once
Assign a descriptive label (e.g., "CI Pipeline", "Partner Integration")

Using the API Key¶

Include the key in the Authorization header of every request:

curl -H "Authorization: Bearer vell_pk_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     https://api.vell.ai/api/v1/partners/profile

Key Lifecycle¶

Action	How
Generate	Dashboard > Settings > API Keys > Generate
Rotate	Generate a new key, update your systems, then revoke the old key
Revoke	Dashboard > Settings > API Keys > Revoke

Key security

API keys carry the full permissions of the account that created them. Treat them like passwords.

OAuth 2.1 (MCP Server)¶

The MCP Server uses OAuth 2.1 with scoped tokens for fine-grained access control.

Scopes¶

Scope	Access
`mcp:full`	Full access to all MCP capabilities
`mcp:tools`	List and call tools only
`mcp:resources`	List and read resources only
`mcp:prompts`	List and get prompts only

Token Flow¶

sequenceDiagram
    participant Client
    participant Auth as Vellocity OAuth
    participant MCP as MCP Server

    Client->>Auth: POST /oauth/token (client_credentials)
    Auth-->>Client: access_token + scopes
    Client->>MCP: POST /api/v1/mcp (JSON-RPC)
    Note over Client,MCP: Authorization: Bearer <oauth_token>
    MCP-->>Client: JSON-RPC response

Two-Layer Authorization¶

MCP requests are authorized at two levels:

OAuth scope — Does the token have the required scope? (e.g., mcp:tools for tools/call)
Team capabilities — Does the user's team role permit the action? (e.g., manage_content for content tools)

Both layers must pass for the request to succeed.

Token Authentication (Calendar Feeds)¶

GTM Schedule ICS feeds use a unique per-user token in the URL, allowing calendar apps to subscribe without OAuth:

https://api.vell.ai/api/v1/gtm-schedule/feed.ics?token=YOUR_FEED_TOKEN

Managing Feed Tokens¶

Endpoint	Description
`POST /api/v1/gtm-schedule/subscription`	Create a feed subscription and get a token
`POST /api/v1/gtm-schedule/subscription/regenerate`	Regenerate the token (invalidates the old one)

See GTM Schedule API for details.

Security Best Practices¶

Do¶

Store API keys in environment variables or a secrets manager
Rotate keys on a regular schedule (at minimum quarterly)
Use the most restrictive authentication method for your use case
Set up IP allowlisting for production keys (Dashboard > Settings > Security)
Use separate keys for development, staging, and production

Don't¶

Embed API keys in client-side code (JavaScript, mobile apps)
Commit keys to version control
Share keys across teams — generate one per integration
Log full request headers in production (mask the Authorization value)

Error Responses¶

Authentication failures return standard error responses:

401 Unauthorized — Missing or invalid token¶

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden — Valid token, insufficient permissions¶

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have access to this resource"
  }
}

See Errors & Rate Limits for the complete error reference.