Skip to content
Viresso. Documentation Open Viresso
Connect & automate4 min read

API Access

On this page

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 for setup and API Authentication for the API flow.

Suspension and API access

API requests to a suspended workspace return 403 Forbidden. See Workspace Suspension for details.