> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Open Workspace settings → API keys">
    You must be an admin or owner of the workspace.
  </Step>

  <Step title="Click 'Create new key'">
    Give it a descriptive name (`zapier-integration`, `internal-dashboard`, `ci-pipeline`).
  </Step>

  <Step title="Choose scopes">
    Default is full access. For tighter security, scope to specific resources (e.g., `projects:read` only). See [Scopes](#scopes) below.
  </Step>

  <Step title="Set an expiration (optional)">
    Keys can expire after a set duration (30 days, 90 days, 1 year). Useful for temporary access.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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**.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.vly.ai/v1/projects \
    -H "Authorization: Bearer $VLY_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.vly.ai/v1/projects", {
    headers: { Authorization: `Bearer ${process.env.VLY_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, httpx
  res = httpx.get(
      "https://api.vly.ai/v1/projects",
      headers={"Authorization": f"Bearer {os.environ['VLY_API_KEY']}"},
  )
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.vly.ai/v1/projects", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VLY_API_KEY"))
  ```
</CodeGroup>

<Warning>
  Never commit API keys to source control. Use environment variables and a secrets manager. See [Secrets management](/security/secrets-management).
</Warning>

### With the SDKs

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Vly } from "@vly/sdk";

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

    const projects = await vly.projects.list();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from vly import Vly

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

    projects = vly.projects.list()
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    export VLY_API_KEY=vly_live_...

    vly projects list
    ```
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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 [api@vly.ai](mailto:api@vly.ai). The full OAuth reference is forthcoming.

## Key rotation

Rotate keys periodically and immediately if you suspect compromise:

<Steps>
  <Step title="Create a new key">
    Same workspace, same scopes. Note its name distinctively (`prod-2026-04` etc.).
  </Step>

  <Step title="Update consumers to use the new key">
    Deploy the change to your code, scripts, integrations.
  </Step>

  <Step title="Verify the new key works">
    Watch logs / monitoring; confirm no unexpected `401`s.
  </Step>

  <Step title="Revoke the old key">
    From the API keys settings page. Revocation takes effect immediately.
  </Step>
</Steps>

## 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](/features/workspace/audit-logs).

## Security best practices

<CardGroup cols={2}>
  <Card title="Never commit keys to source control" icon="shield-alert">
    Use `.env`, environment variables, or a secrets manager. Add `*.env*` to `.gitignore`.
  </Card>

  <Card title="Use scoped keys" icon="key-square">
    A read-only key is much less dangerous if leaked than a full-access key. Default to least privilege.
  </Card>

  <Card title="Set expirations on temporary keys" icon="clock">
    For one-off scripts or short-lived integrations, set an expiration so forgotten keys auto-revoke.
  </Card>

  <Card title="Rotate keys quarterly" icon="repeat">
    Even without suspected compromise, periodic rotation limits exposure window.
  </Card>

  <Card title="Use OAuth for third-party apps" icon="users">
    Don't ask other users for their vly API key. Use OAuth so customers can audit and revoke from their side.
  </Card>

  <Card title="Monitor unexpected usage" icon="activity">
    Set up alerts in vly's dashboard for spikes in API usage — a sign that a key might be compromised.
  </Card>
</CardGroup>

## Errors

Authentication errors return `401 Unauthorized`:

```json theme={null}
{
  "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](/api-reference/rate-limits). |

## Related

<CardGroup cols={3}>
  <Card title="API introduction" icon="book-open" href="/api-reference/introduction">
    Base URLs, common patterns, SDKs.
  </Card>

  <Card title="Errors" icon="alert-triangle" href="/api-reference/errors">
    Full error code reference.
  </Card>

  <Card title="Webhooks SDK" icon="webhook" href="/api-reference/sdks/webhooks">
    Webhook signature verification.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.