# API Access

To access the Viresso API programmatically, you need an **API key** created in Viresso. API keys are scoped to a single workspace and can optionally restrict which origins can use them.

## Creating an API key

1. Go to **Settings → API Keys**.
2. Click **Add Key**.
3. Enter a **Key Name** (max 16 characters, unique within the workspace).
4. Optionally, set an **Origin** restriction (e.g. `https://example.com` or `*.example.com`).
5. Choose **Full access** or select the required abilities. For uploads, enable **Upload files** (`files:write`); for deletions, enable **Delete files** (`files:delete`).
6. Click create.

> Info: The API key is shown only once, at creation time. Copy it immediately and store it securely.

## Authenticating requests

Pass the API key via the `Authorization` header:

```
Authorization: Bearer {api_key}
```

API keys are not accepted in query parameters.

## Origin restrictions

API keys can restrict which HTTP origins can use them:

| Origin setting | Behavior |
|---|---|
| (empty) | No restriction — any origin can use the key |
| `https://example.com` | Requests whose normalized origin host is `example.com` are allowed |
| `*.example.com` | Any subdomain of `example.com` is allowed (but not the apex domain) |
| `*` | All origins allowed |

Origin checks compare the normalized host and non-default port in the request’s `Origin` header against the key’s restriction pattern. Scheme and path are not part of this API-key comparison. A restricted key also rejects requests without an `Origin` header. `*.example.com` matches subdomains such as `app.example.com` and `admin.app.example.com`, but not `example.com` itself.

An origin mismatch returns `403 Forbidden`.

- For **browser-based clients**, create keys with origin restrictions matching your application domain.
- For **server-side integrations**, create keys without origin restrictions.

## Rate limiting

API requests use separate limits based on the API key, capability URL, or hosted-auth credential:

| Endpoint group | Limit and scope |
|---|---|
| Entries | 500 units per minute per API key; one per request, or one per query in a read batch |
| File uploads | 60 requests per minute per API key |
| File deletions | 60 requests per minute per API key |
| Tokenized file downloads | 1,200 requests per minute per capability URL |
| Pipeline execution | 30 requests per minute per API key |
| Transactional mail | 10 requests per minute per API key |
| Hosted auth login | 10 requests per minute per email and 60 per IP |
| Hosted auth verification | 10 requests per minute per OTP and 120 per IP |
| Hosted auth token exchange | 60 requests per minute per IP |
| Hosted auth session validation | 600 requests per minute per access token |

Exceeded requests return `429 Too Many Requests`. Check the `Retry-After` header to know when to retry.

Rate limiting and automatic throttle bans are disabled by default in local and test environments. Set `RATE_LIMITING_ENABLED=true` and `AUTO_BAN_ENABLED=true` to exercise production behaviour locally.

Automatic IP bans are only triggered by repeated throttling on abuse-sensitive operations: requesting login codes, sending mail, and executing pipelines. File delivery, entry reads, and session validation can return `429` without globally blocking the client IP.

## API key security

- API keys are 256-character random strings.
- The key value is stored hashed and cannot be retrieved after creation.
- Keys are hidden from API responses and list views (only the name is shown).
- Rotate a key to immediately invalidate the old value and reveal a new value once.
- Revoke a key by deleting it from the API Keys settings page.

## API key permissions

Keys can be granted full access or a limited set of abilities:

| Ability | Access |
|---|---|
| `entries:read` | List and read published entries |
| `entries:query` | Query draft and published entries, including related content, with field selection and filters |
| `entries:write` | Create and update entries |
| `files:write` | Upload workspace files |
| `files:delete` | Permanently delete workspace files and remove their entry attachments |
| `entries:delete` | Permanently delete entries |
| `pipelines:execute` | Execute active pipelines |
| `mail:send` | Send transactional email |

You can change a key’s abilities from its edit form without rotating its value. Full access uses the `*` wildcard.

For operations with workspace permissions, a key cannot exceed the permissions of the member who created it. For example, granting `entries:write` does not let a read-only member's key create entries.

File downloads use their tokenized URL and do not require an API key. File uploads require `files:write` and the creator’s `create-file` permission. File deletions require `files:delete` and the creator’s `delete-file` permission; upload-only keys cannot delete files. System keys without a recorded creator still enforce their granted abilities.

## Hosted authentication

Hosted authentication is separate from API key access. It provides passwordless app login based on a configured content type with an email field in your workspace. See [Hosted Login](/docs/platform/hosted-login) for setup and [API Authentication](/docs/api/authentication) for the API flow.

## Suspension and API access

API requests to a suspended workspace return `403 Forbidden`. See [Workspace Suspension](/docs/platform/workspace-suspension) for details.

## Related pages

- [Hosted Login](/docs/platform/hosted-login) — Configure hosted login pages.
- [API Authentication](/docs/api/authentication) — Hosted authentication endpoints.
- [Workspace Suspension](/docs/platform/workspace-suspension) — How suspension affects API access.
- [Workspace Settings](/docs/platform/workspace-settings) — Managing API keys.