Authentication
Authenticated API requests use a bearer credential in the Authorization header. The organization in the request URL and the permissions attached to that credential determine which records and operations are accessible.
Authorization: Bearer <credential>
Organization API keys
Organization API keys authorize an integration to perform explicitly granted operations in that organization. Creating or maintaining a key requires the corresponding API-key management permissions on your user or authorized client.
Key management supports a name, enabled state, optional expiry date and a permission list. An empty permission list grants no operations. Grant the operations the integration needs, rather than assuming a key has the same access as an administrator.
See the API key reference for the management operations and their request schemas.
The credential is returned only when the key is created. Store it at that point; ordinary key-detail responses do not return it again. Send it in the bearer header, not in the URL.
Existing access tokens
The API also accepts supported bearer access tokens from Zenvio authentication. Use the authentication flow configured for your authorized application. Do not substitute an organization identifier or an API-key ID for a credential.
An organization API key is scoped to organization operations. It cannot be used to manage credentials or to call personal account endpoints merely because those endpoints appear in the reference.
Expiry and revocation
Keys can have an optional expiry date. Revocation is permanent. Enabled-state changes and revocation may take a short time to propagate through authentication caching, so do not assume a configuration change is visible everywhere immediately.
Diagnose access failures
| Response | What to check |
|---|---|
401 Unauthorized | Credential validity, expiry, enabled state and the bearer header |
403 Forbidden | Organization access and permissions for the requested operation |
Check the endpoint's response details for other errors. A valid credential does not grant access to every endpoint.
Interactive reference examples
The current OpenAPI specification does not declare an authentication scheme. Its generated examples may therefore omit the authorization header. Include the bearer header when calling an authenticated endpoint, even if an example does not show it.
Continue with Getting started to construct a first read request.