Authentication

How to authenticate to the vly.ai REST API. API keys, OAuth, scopes, key rotation, and security best practices.

The vly.ai API uses bearer authentication via API keys. Every request must include an Authorization header with a valid key.

API keys

API keys are workspace-scoped: each key authorizes access to one workspace’s resources. Generate keys from Workspace settings → API keys.

Key formats

Prefix	Environment	Purpose
vly_live_...	Production	Real workspace data
vly_test_...	Test	Sandbox; no real charges, isolated test data

Test keys are useful when integrating: you can build against the API without risking production data. Switch to live keys when you ship.

Generating a key

1. Open Workspace settings → API keys

   You must be an admin or owner of the workspace.

2. Click 'Create new key'

   Give it a descriptive name (zapier-integration, internal-dashboard, ci-pipeline).

3. Choose scopes

   Default is full access. For tighter security, scope to specific resources (e.g., projects:read only). See Scopes below.

4. Set an expiration (optional)

   Keys can expire after a set duration (30 days, 90 days, 1 year). Useful for temporary access.

5. Copy and store the key

   The key is shown once — copy it now. You won’t see it again. Store in a secrets manager or environment variable.

Using a key

Pass the key in the Authorization header as a bearer token:

All requests to the vly.ai API must include your API key in the Authorization header as a bearer token. Generate keys from your Workspace settings → API keys.

curl

curl https://api.vly.ai/v1/projects \
  -H "Authorization: Bearer $VLY_API_KEY"

Never commit API keys to source control. Use environment variables and a secrets manager. See Secrets management.

With the SDKs

TypeScript

import { Vly } from "@vly/sdk";

const vly = new Vly({ apiKey: process.env.VLY_API_KEY });

const projects = await vly.projects.list();

Python

import os
from vly import Vly

vly = Vly(api_key=os.environ["VLY_API_KEY"])

projects = vly.projects.list()

CLI

export VLY_API_KEY=vly_live_...

vly projects list

Scopes

Scopes limit what a key can do. Useful for keys that only need to read data, or only manage specific resource types.

Scope	Permits
projects:read	List, get projects
projects:write	Create, update, delete projects
deployments:read	List, get deployments
deployments:write	Create deployments, rollback
agents:run	Trigger agent runs
files:read	List, download files
files:write	Upload, delete files
billing:read	Read usage and invoices
webhooks:read	List webhook configs
webhooks:write	Create, update, delete webhooks
*	Full access (default)

Combine scopes by listing multiple in the API key creation dialog.

OAuth (for third-party integrations)

If you’re building a public integration that other vly customers will install, use OAuth 2.0 instead of asking customers for their API key.

GET https://app.vly.ai/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=projects:read+deployments:read
  &state=RANDOM_NONCE

After the user authorizes, they’re redirected to your callback URL with an authorization code. Exchange the code for an access token:

curl -X POST https://app.vly.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "...",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Use the returned access_token exactly like an API key.

To register an OAuth app, contact [e-mail]. The full OAuth reference is forthcoming.

Key rotation

Rotate keys periodically and immediately if you suspect compromise:

1. Create a new key

   Same workspace, same scopes. Note its name distinctively (prod-2026-04 etc.).

2. Update consumers to use the new key

   Deploy the change to your code, scripts, integrations.

3. Verify the new key works

   Watch logs / monitoring; confirm no unexpected 401s.

4. Revoke the old key

   From the API keys settings page. Revocation takes effect immediately.

Audit log

Every API request is logged with the key used, the endpoint, the IP, and the response status. View the audit log in Workspace settings → Audit log, filtered to API events. Useful for:

• Verifying a key isn’t being abused.
• Debugging “why did this resource get deleted?” — the audit log answers.
• Compliance reporting.

See Audit logs.

Security best practices

Never commit keys to source control

Use .env, environment variables, or a secrets manager. Add *.env* to .gitignore.

Use scoped keys

A read-only key is much less dangerous if leaked than a full-access key. Default to least privilege.

Set expirations on temporary keys

For one-off scripts or short-lived integrations, set an expiration so forgotten keys auto-revoke.

Rotate keys quarterly

Even without suspected compromise, periodic rotation limits exposure window.

Use OAuth for third-party apps

Don’t ask other users for their vly API key. Use OAuth so customers can audit and revoke from their side.

Monitor unexpected usage

Set up alerts in vly’s dashboard for spikes in API usage — a sign that a key might be compromised.

Errors

Authentication errors return 401 Unauthorized:

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing or invalid API key. See https://docs.vly.ai/api-reference/authentication"
  }
}

Code	Meaning
missing_api_key	No Authorization header.
invalid_api_key	Key not recognized or revoked.
expired_api_key	Key passed its expiration.
insufficient_scope	Key valid but missing the required scope for this endpoint.
key_rate_limited	Too many requests from this key. See Rate limits.

Related

API introduction

Base URLs, common patterns, SDKs.

Errors

Full error code reference.

Webhooks SDK

Webhook signature verification.