External REST integration (API key)

An external REST integration is a controlled "door" through which another system (an ERP, a website backend, 1C, an integration layer, or your own application) can create and update tasks and deals in LadVen OS over a standard API with an access key. And nobody hands over a login and password or works under an administrator.

Every call runs as a separate service account (a bot) with the minimum permissions needed: only the actions you allowed, and only in the departments, projects, pipelines, and stages you defined. All requests go through the portal's normal rules — access, checks, automation, notifications — and are written to a log you can review per integration.

A connection is added once in the integration hub (CRM → Integrations, route /crm/integrations).

When to use it

A REST integration is what you need when "something happens in another system — and a task or deal should appear in LadVen OS automatically." Typical scenarios:

• an ERP or website creates a task or inquiry when an order, request, or ticket comes in;
• your own application keeps tasks and deals in sync with an external database;
• an external system attaches files, leaves comments, logs time, or moves a deal through its stages as work progresses on the other side.

How this differs from forms and webhooks: a website form and a webhook are a one-way intake of requests into CRM. A REST integration is a programmatic two-way link: the external system both reads (gets tasks, deals, history) and writes (creates and updates). The portal itself does not send outbound webhooks through this connection — the external side reaches out to the portal on its own.

How to set it up

A connection is created with a step-by-step wizard (CRM → Integrations → add "External REST integration"). Step by step, in practical terms:

1. Name and activity. Give the integration a clear name and decide whether to enable it right away. You can run a connection check straight away.
2. Service account. Pick an existing bot or create a new one right in the wizard (name, login, and email). A new account is an active bot user without administrator rights; its password is generated only for the backend contract and is not used by the wizard. This is not an employee and not an administrator: the integration acts on its behalf. If you pick an account with administrator permissions, the wizard will warn you — that's by design, integrations are given the minimum permissions.
3. Scenario and permission level. Choose the set of operations for the job: "Tasks and CRM", "Tasks only", or "CRM only". Then the permission level: read only, create and edit, or manage. Permissions are applied to the service account before the key is issued.
4. Allowed actions. Tick the specific operations the integration is allowed to perform. The principle is "the minimum needed": enable only what is actually required. Anything not ticked will be rejected before it runs.
5. Scope. Restrict the integration to the departments, projects, pipelines, and stages you need. This is a frame on top of the account's permissions: even an allowed action will only work inside the defined scope.
6. Fields and limits. Set which task and deal fields the integration may change, the request limit per minute and the allowed burst, and the whitelist of IP addresses from which calls are permitted.
7. Key creation and verification. Save it — the portal will show the access key once on the results screen with a copy button. From here you can also run a connection check.

If the selected service account already has its rights, choose Rights are already configured: the wizard does not change ACL and checks the resulting access only during the connection test. In setup mode the wizard applies the selected rights before allowing token creation. A selected CRM stage automatically adds its pipeline to the integration scope; an empty project, pipeline, or stage list does not expand the account's rights.

The method catalog is grouped into tasks, task checklists/time/files/history, CRM companies and contacts, activities, appeals, and other methods. A scenario (Tasks + CRM, Tasks only, or CRM only) is only a shortcut; the token request contains the actual allowlist of checked methods. The request log records operations and their results.

After it is created, the connection has a request log: which operations were called and with what result. Its detailed view is currently a technical diagnostic surface: do not open, copy, or publish request/response/error values, identifiers, reason codes, or error text from it. For investigation, give the integration owner only the time and connection name through an approved secure channel.

Additional wizard rules

If the service account already has its rights, choose Rights are already configured: the wizard does not change ACL and checks access during the connection test. In setup mode, selected rights are applied before token creation. A selected CRM stage adds its pipeline to the integration scope automatically; an empty project, pipeline, or stage list does not expand account rights. The method catalog groups task and CRM methods, and the log records operations and results.

Security and the access key

A REST integration is built on the principle of least privilege — which matters for the business owner:

• The key is shown once. Copy it and save it in a secrets manager right away. The portal will not show this key again and does not store it in plain text. If the key needs to change, reissue it by going through the wizard for this connection again.
• A separate service account. The integration does not act as a person or an administrator; it has its own area of responsibility and its own permissions.
• Access boundaries. The allowed actions, the scope (departments, projects, pipelines, stages), the field whitelist, the request limit, and the IP whitelist limit what the integration can do and where from.
• The log. Every call is recorded — you can trace who changed what through the integration.

Never show a real key, authorization header, whitelisted IP addresses, or the service account login in screenshots or publish them. For illustrations, use obviously fake values.

Common mistakes

• Giving the integration an administrator account instead of a service bot.
• Enabling more actions than needed instead of the minimum set.
• Not copying the one-time key when it is created.
• Not setting an IP whitelist and a request limit.
• Setting too broad a scope — the whole portal instead of the one pipeline you need.
• Expecting the portal to start sending outbound webhooks on its own: the integration works through inbound calls, with the external system reaching out to the portal.

How to check that it works

1. Run the connection check at the end of the wizard (or enable the check to run straight away).
2. Make sure the connection card shows an active and healthy state.
3. Look at the request log — there should be successful calls there.
4. Check that a test task or deal appeared with the correct owner, pipeline, and stage, and that automation and notifications ran as usual.

Related pages

• Forms and inbound flow
• Forms
• CRM: overview
• Tasks