Authentication

The Vendo REST API uses account-scoped API keys.

Each key belongs to a single account. Each key has one scope. The scope controls which surface the key can use: the REST API, the MCP server, or both.

Creating an API Key

To create a key, you need the api_keys.admin and api_keys.write permissions. Without api_keys.admin, the API Keys page does not show.

1. In the account dropdown menu, click Workspace Settings.
2. Under Developers, click API Keys.
3. Click New key.
4. In Name, enter the purpose of the key (100 characters or fewer).
5. Under Scope, select a scope. See Scopes.
6. Click Create Key.
7. Copy the key.
8. Click Done.

The full key is only shown once.

API Key Format

vendo_sk_<random-string>

Using Your API Key

Include the key as a bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app2.vendodata.com/api/v1/apps

Scopes

When you create a key, you select one of these scopes:

Every REST API route requires a key with Full access. The REST API refuses a key with an MCP scope with a FORBIDDEN error.

Vendo also authorizes each REST operation. For example, the route that creates an app needs the apps.write permission.

On the MCP server, a key without the mcp:write scope is always read-only, whatever the MCP URL says. For details, see API key scopes.

A key with no scopes shows No scopes in the key list. It cannot call the REST API. On the MCP server, it is read-only.

Example Errors

Missing API key:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Include Authorization: Bearer <your-api-key>"
  }
}

Invalid API key:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid bearer token. The token may be expired, revoked, or incorrect."
  }
}

Insufficient scopes:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key does not have the required scopes: *"
  }
}

Best Practices

1. Use separate keys for production, staging, and local tooling.
2. Use an MCP scope for a key that only an MCP client uses.
3. Rotate keys regularly.
4. Store keys in environment variables or a secrets manager.
5. Revoke unused keys promptly.

Environment Variable Example

export VENDO_API_KEY="vendo_sk_your-key-here"
 
curl -H "Authorization: Bearer $VENDO_API_KEY" \
  https://app2.vendodata.com/api/v1/me