Vera public API

The Vera public API gives you programmatic access to Vera data from external tools, scripts, and automations. You authenticate with an API key instead of a user login, so your integrations don't depend on an interactive session. This topic explains how the API works, what you can do with it, and what to expect when something goes wrong.

To get an API key, ask your Vera administrator. Admins create and manage keys from the API Keys page in the administration area.

Authenticate with an API key

All requests to the public API must include your API key in the request header:

X-API-Key: <your-api-key>

You receive your API key once, when the administrator creates it. Copy it immediately. Vera can't show the full key again after that point. If you lose it, ask your administrator to rotate or create a new key.

The public API is not intended for use directly from a browser. Use it from server-side scripts, CI/CD pipelines, or controlled automation tools instead.

Understand key authorization

Every API key is bound to a specific Vera user. Your effective access through the API is the combination of that user's permissions and the scopes assigned to the key. If the user has access to a domain but the key wasn't granted the matching scope, the API call won't succeed.

When the bound user is deactivated or deleted in Vera, the key stops working immediately. There is no grace period. Plan your integrations accordingly, and make sure the user account tied to your key stays active.

Required secrets

The vera-api-public service requires two secrets, configured by your administrator before the service starts:

Variable	Description
VERA_CLIENT_SECRET_PUBLIC_API	The client secret for the public_api_service identity server client.
VERA_API_KEY_PEPPER	A secret used to hash API keys. The value must match between the vera-api-public service and the Vera Server. If the values don't match, key validation fails and you can't authenticate.

For full configuration details, check out Set up the public API service.

Allowed operations

The public API uses the versioned prefix /api/v1/. It supports read-oriented access and a limited set of POST operations on allowlisted paths. The following operations are available:

• Search and retrieve records using GET endpoints.

• Filter records and query workflows using allowlisted POST endpoints, such as filter and traceability queries.

• Retrieve audit history where permitted.

The public API is not a full REST mirror of the internal API. Internal and mutation paths are not exposed. If you're looking for a specific endpoint, check the Vera API Enablement deck (PPTX) for the full list of available operations.

Handle rate limits

Each API key has a per-minute rate limit. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header that tells you how many seconds to wait before retrying. Your integration should read this header and back off accordingly.

Your administrator can configure a custom rate limit override for your key. If your workload regularly hits the default limit, ask your administrator to adjust it.

Understand error responses

The public API returns errors in the Problem Details format (RFC 7807). Each error response includes a machine-readable type and a human-readable detail field. The most common error codes are:

Status	Meaning	What to do
401 Unauthorized	Missing or invalid API key.	Check that the X-API-Key header is present and correct.
403 Forbidden	Key is valid but doesn't have permission for this operation.	Ask your administrator to check the key's scopes and the bound user's permissions.
429 Too Many Requests	Rate limit exceeded.	Wait the number of seconds in the Retry-After header, then retry.
503 Service Unavailable	The public API service is temporarily unavailable.	Retry after a short delay. Contact your administrator if the issue persists.

Key lifecycle

API keys can expire, be revoked, or become inactive. When a key stops working, your requests return 401 Unauthorized. The most common reasons are:

• The key reached its expiration date.

• An administrator revoked or deactivated the key.

• The Vera user the key is bound to was deactivated or deleted.

Your administrator can rotate a key if it's compromised. During a rotation, the old key remains valid until the grace period ends, giving you time to update your integration before access cuts off.

What's next

Now that you understand how the public API works, here's what you can do next:

• See the Vera API Enablement deck (PPTX) for more instructions and examples on using the Vera API.

• Manage API keys to create, edit, rotate, or revoke keys in the administration area.