Configure and use the scoped integration API

Product Zbix CRM · Version 1.2.0 · Source reviewed · Reviewed 28 October 2026
Audience Administrators and implementation teams · Deployment All supported models

Overview

The bearer API supports list, detail and create operations for Leads, Contacts, Accounts and Deals. Each credential is bound to an active non-administrator service identity and explicit read/create scopes. Requests also enforce that user’s current module permission and record visibility. Credential creation, rotation and revocation are administrator operations.

Purpose

Use the scoped API for controlled record ingestion or retrieval without distributing a browser session or administrator password.

Prerequisites

• Integration API enabled by the installation owner and a licensed capability where applicable.

• An active non-administrator service identity with the necessary CRM permissions.

• A secure application secret store for the token shown at creation or rotation.

Procedure

1. Open Administration > Integrations and review Local configuration. Resolve disabled API status through the installation owner before creating a credential.

2. Choose Create API credential, name the integration, select its service identity and grant only the required read/create scopes. Set an expiry and request rate limit.

3. Store the returned token securely when shown. Do not place it in source code, documentation, URLs or logs.

4. Call the /api/v1/{module} list or detail endpoint using the Authorization bearer header. Page through results with page and page_size; page_size is limited to 100.

5. For POST creation, provide an Idempotency-Key unique to that logical operation. Retries of identical content retain the same key; changed content requires a different key.

6. Verify the created record and audit result. Rotate credentials before expiry and revoke those no longer required.

Expected result

The integration can perform only the granted read/create actions within its service identity’s scope.

Screenshots and diagrams

SS-047 · Integrations & API credentials. Demonstration capture, 28 October 2026. Select the image to enlarge.

Important notes

• Credential expiry defaults to 30 days and cannot exceed 365 days. Rate limits range from 1 to 600 requests per minute, defaulting to 60.

• Integration-created records must belong to the scoped service identity. Update, delete, bulk export and every browser endpoint are not implied by these scopes.

• Create bodies are bounded to 64 KiB of finite JSON. A reused idempotency key with different content is rejected.

• Rotation invalidates the previous token; revoked credentials cannot be rotated.

Troubleshooting

• 401: check expiry, revocation, token rotation and service-account activity.

• 403: check both explicit credential scope and the service user’s current module permissions.

• 429: wait for the next minute window before retrying.

• 409 on a create retry: compare the idempotency key and exact intended request content.

Related articles

• Integration interfaces and provider boundaries

• Authorization and permission evaluation

• API validation and safe concurrency