Authentication¶

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

Authentication Methods¶

Method	Used By	Header Format
OAuth 2.0 (Passport) bearer token	All `/api/v1` endpoints	`Authorization: Bearer ACCESS_TOKEN`
Partner key (`vp3_…`)	MCP Server (`/api/v1/mcp`) only	`Authorization: Bearer vp3_...` or `X-Partner-Key: vp3_...`
Token URL	GTM Schedule ICS feeds	`?token=FEED_TOKEN` (query parameter)

OAuth 2.0 Bearer Tokens¶

All /api/v1 endpoints are authenticated with an OAuth 2.0 access token (Laravel Passport). Include it in the Authorization header of every request:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     https://api.vell.ai/api/v1/user

Tokens are issued through Vellocity's OAuth 2.0 token endpoint (/oauth/token). The MCP Server section below documents a complete client-credentials flow; to obtain OAuth client credentials for broader /api/v1 access, apply through the Embedded Partner Program.

“Settings → API Keys” is not this

The Settings → API Keys screen in the dashboard stores your own AI-provider credentials (OpenAI, Anthropic, Gemini, and your AWS Bedrock role/keys) so Vellocity can call those providers on your behalf. It does not issue a Vellocity API token — don't use those values to authenticate to this API.

Partner Keys (MCP Server)¶

Partner keys (vp3_…) authenticate the MCP Server endpoint (/api/v1/mcp) only — they do not authenticate other /api/v1 routes. Present the key as a bearer token or in the X-Partner-Key header:

curl -H "Authorization: Bearer vp3_..." \
     -H "Content-Type: application/json" \
     https://api.vell.ai/api/v1/mcp

Partner keys are created, rotated, and revoked through the Embedded Partner Program endpoints (which are themselves OAuth-authenticated). Each key can carry scoped capabilities, an IP allowlist, a per-minute rate limit, and a daily credit limit. The plaintext key is shown once, at creation.

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.