> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veri.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and model access keys

> Store credentials once, hand agents and external tools a key that can only call one deployment

## Overview

Two small primitives keep credentials out of places they do not belong:

* **Secrets** are workspace-scoped named values (`OPENAI_API_KEY`, `GITHUB_TOKEN`, ...) stored encrypted. The API never returns a value once stored. Agent environments reference secrets by name.
* **Model access keys** are API keys bound to one deployment. They authenticate only that deployment's inference routes, so you can give one to an agent sandbox, a coding assistant or another hosting provider without exposing your workspace.

## Secrets

Names follow environment-variable syntax (`[A-Za-z_][A-Za-z0-9_]{0,63}`), because that is how agent sessions receive them.

```bash theme={null}
# Prefer --from-env or --stdin so the value never lands in shell history.
export OPENAI_API_KEY=sk-...
veri secrets set OPENAI_API_KEY --from-env OPENAI_API_KEY --scope-host api.openai.com

veri secrets list
veri secrets delete OPENAI_API_KEY
```

```python theme={null}
from veri_sdk import Client

client = Client()
client.secrets.set("GITHUB_TOKEN", token)                       # injected as an env var
client.secrets.set("OPENAI_API_KEY", key, scope_host="api.openai.com")
client.secrets.list()   # names and metadata only
```

```bash theme={null}
curl -X PUT https://api.veri.studio/v1/secrets/OPENAI_API_KEY \
  -H "Authorization: Bearer $VERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "sk-...", "scope_host": "api.openai.com"}'
```

| Field | Meaning |
| - | - |
| `value` | The secret. At most 64 KiB. Encrypted at rest, never returned. |
| `scope_host` | Optional bare hostname (`api.openai.com`). When set, agent sessions attach the value only to HTTPS requests for that host, and the value itself never enters the sandbox. When absent, the value is injected as an environment variable named after the secret. |

`PUT` on an existing name replaces the value in place. Secrets are visible only inside the workspace that created them.

## Model access keys

A normal API key can do everything in your workspace. A model access key can do exactly four things, all on one deployment:

| Method | Route |
| - | - |
| `GET` | `/v1/deployments/{id}` |
| `POST` | `/v1/deployments/{id}/chat/completions` |
| `POST` | `/v1/deployments/{id}/messages` |
| `POST` | `/v1/deployments/{id}/messages/count_tokens` |

Everything else, including other deployments, returns `401`.

```bash theme={null}
veri api-keys create agent-prod --deployment dep1a2b3c4d5e --expires-in 86400
# prints the key once

veri api-keys list
veri api-keys revoke <key_id>
```

```python theme={null}
key = client.api_keys.create("agent-prod", deployment_id="dep1a2b3c4d5e", expires_in_seconds=86400)
key["key"]      # plaintext, returned once
key["kind"]     # "model_access"
```

Point any OpenAI-compatible client at the deployment with this key:

```bash theme={null}
OPENAI_BASE_URL=https://api.veri.studio/v1/deployments/dep1a2b3c4d5e \
OPENAI_API_KEY=vk_... \
your-agent
```

| Field | Meaning |
| - | - |
| `deployment_id` | Binds the key to one deployment. The deployment must belong to the workspace minting the key. |
| `expires_in_seconds` | Optional lifetime, 60 seconds to one year. An expired key is rejected exactly like a revoked one. |
| `kind` | `user` for a full key, `model_access` for a deployment-bound key. |

Managed agent sessions mint a short-lived model access key per session automatically when an environment's model is a Veri deployment.


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