# Public access

> Set how many sessions website visitors may start, how long they last, and what they agree to first.

Source: https://docs.vlayers.ai/developers/public-access

Kind: How-to guide

## What you'll build

Limits for the visitors who talk to your agent from your website, set from the dashboard or from code, and a way to see why a visit was turned away.

A visitor reaches an agent through a **website key**: the publishable key behind the [voice button](https://docs.vlayers.ai/build/website-voice-button). Public access decides whether that key is open, and how much it may do.

## How the limits stack

Limits are set at four levels: the platform and your plan, your workspace, one agent, and one website key. Levels only tighten. A cap is the lowest of them, and any "off" wins. A website key is open only when its own row says `enabled: true`, for the agent it was enabled for. Pointing the key at a different agent turns it off again.

| Setting | Range | Meaning |
|---|---|---|
| `enabled` | true or false | Whether sessions are allowed |
| `sessionsPerDay` | 0 to 500 | Sessions a key admits per day |
| `concurrentSessions` | 0 to 10 | Sessions at the same time |
| `perIpPerHour` | 1 to 20 | Sessions from one address per hour |
| `maxCallMinutes` | 1 to 5 | Longest session |
| `perSenderPerDay` | 1 to 10 | Replies one sender gets per day (messaging) |
| `botCheck` | `on` or `off` | Whether visitors pass a bot check first |
| `consent` | `privacyUrl`, `statements` | What the visitor agrees to before the call starts |

The consent step needs a privacy policy address (`consent.privacyUrl`) before public access can be on. `statements` is 1 to 8 sentences of up to 200 characters. Left out, the defaults are used.

## Prerequisites

- A secret API key with `public_access:read` to read and `public_access:write` to change. See [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication).
- A website key. Create it in the dashboard under **Settings → Workspace → Public access**, where you also set the daily budget, the bot check and the limits.

> **Note:** **Who may loosen a limit.** A key may tighten: turn public access off or lower a cap. Turning it on, raising a cap, turning the bot check off and changing the bot check's keys need a workspace admin. A key that asks gets `403 forbidden`. Enabling a website key also needs a hard daily budget on the key that covers every session it may run at once.

## Step 1: See what is set

`GET /v1/public-access/settings` returns one row for the workspace, one per agent and one per website key. Each row has a `version`. Send it back as the `If-Match` header on the next write so you never overwrite a newer change.

cURL:

```bash
curl https://api.vlayers.ai/v1/public-access/settings \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { settings } = await voicelayer.publicAccess.list();
console.log(settings);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.list()
print(result.settings)
```

## Step 2: See what a visitor gets right now

`GET /v1/public-access/effective?keyId=…` resolves the result for one website key: whether it is open, why not when it is not (`offReason`), each cap, and which level decided each value (`sources`).

cURL:

```bash
curl "https://api.vlayers.ai/v1/public-access/effective?keyId=$WEBSITE_KEY_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { open } = await voicelayer.publicAccess.effective({ keyId: '<website-key-id>' });
console.log(open);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.effective(key_id="<website-key-id>")
print(result.open)
```

## Step 3: Change a limit

Each level has a `PUT` that sets only the fields you send and a `DELETE` that removes the row, so that level inherits again. Add a `note` to say why; it goes in the change log.

Pause all public sessions in the workspace:

cURL:

```bash
curl -X PUT https://api.vlayers.ai/v1/public-access/settings/workspace \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "enabled": false
    },
    "note": "Pausing public sessions during the launch review"
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { version } = await voicelayer.publicAccess.setWorkspace({
  settings: { enabled: false },
  note: 'Pausing public sessions during the launch review'
});
console.log(version);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.set_workspace(
    settings={
        "enabled": False,
    },
    note="Pausing public sessions during the launch review",
)
print(result.version)
```

Allow one agent at most one session at a time:

cURL:

```bash
curl -X PUT "https://api.vlayers.ai/v1/public-access/settings/agents/$AGENT_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "concurrentSessions": 1
    }
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { version } = await voicelayer.publicAccess.setAgent('<agent-id>', {
  settings: { concurrentSessions: 1 }
});
console.log(version);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.set_agent(
    "<agent-id>",
    settings={
        "concurrentSessions": 1,
    },
)
print(result.version)
```

Set a website key's daily sessions:

cURL:

```bash
curl -X PUT "https://api.vlayers.ai/v1/public-access/settings/bindings/$BINDING_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "sessionsPerDay": 20
    }
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { version } = await voicelayer.publicAccess.setKey('<binding-id>', {
  settings: { sessionsPerDay: 20 }
});
console.log(version);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.set_key(
    "<binding-id>",
    settings={
        "sessionsPerDay": 20,
    },
)
print(result.version)
```

Remove a row:

cURL:

```bash
curl -X DELETE "https://api.vlayers.ai/v1/public-access/settings/agents/$AGENT_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

await voicelayer.publicAccess.removeAgent('<agent-id>');
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

vl.publicAccess.remove_agent("<agent-id>")
```

`deleteWorkspacePublicAccess` and `deleteBindingPublicAccess` do the same for the workspace and a key. Removing a row that said "off" loosens, so it needs an admin. Removing a key's row turns public access off for that key.

## Step 4: See why visits were turned away

`GET /v1/public-access/usage?keyId=…` counts today (UTC): sessions admitted and ended, and attempts turned away with the reason. A visitor sees one generic message; you see why.

cURL:

```bash
curl "https://api.vlayers.ai/v1/public-access/usage?keyId=$WEBSITE_KEY_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { admitted } = await voicelayer.publicAccess.usage({ keyId: '<website-key-id>' });
console.log(admitted);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.publicAccess.usage(key_id="<website-key-id>")
print(result.admitted)
```

```json
{
  "keyId": "key_9b3d42",
  "since": "2026-10-20T00:00:00.000Z",
  "admitted": 12,
  "ended": 11,
  "refusals": [{ "reason": "challenge_failed", "count": 3 }, { "reason": "ip_rate", "count": 1 }]
}
```

Pair it with the key's daily budget to watch spend.

## From a chat assistant

Over [MCP](https://docs.vlayers.ai/developers/mcp), `public_access_get` reads the settings and `public_access_tighten` lowers them. Loosening stays with a workspace admin in the dashboard.

## Test it

Read the effective settings for your key, lower `sessionsPerDay` to 1 with `putBindingPublicAccess`, read them again, and check that `sources.sessionsPerDay` names the key's level.

## Next steps

- [Voice button on your website](https://docs.vlayers.ai/build/website-voice-button).
- [Access and keys](https://docs.vlayers.ai/get-started/access-and-keys).
