Create an integration
1. Open the integrations screen
In the left menu of the Bito admin panel go to Integration → Integration and press Custom integration. In the Create integration dialog pick the kind:
- External integration — API only: your code runs on your own servers. Press + Create on that row; this page describes this path.
- Integration with custom code — the same form plus a
widget.zipthat runs inside Bito. See a widget for your own account.
2. Fill in the form
Only the name is required at this stage, but a public listing needs most of the rest. You can edit any of it later — except while the card is in review (pending), when changes are refused.
| Field | Required | Description |
|---|---|---|
name | Yes | Per-language name shown in the marketplace. Fill at least one language; the rest are copied from the first one you fill. |
description | No | Per-language description shown before install. |
thumbnail | No | Logo URL. Upload the image first; the form gives you the URL. |
role_id | No | Legacy (Integration role in the form). An integration request runs as the merchant's owner, so this role does not restrict access; it is kept only so older clients that still send it keep working. Restrict access with required_permissions instead. |
required_permissions | No | The ERP permissions this integration uses on the Integration API (the same keys roles are built from). The merchant sees exactly this list before installing, installing grants it to the integration, and every call is checked against it. Empty or omitted means all permissions. The plain form has no such field; set it under My apps → app → General info or over the API. |
redirect_uri | For OAuth | Your HTTPS endpoint. Bito POSTs the authorization code here when a merchant installs the integration. See install hooks. |
revoke_access_hook_uri | Strongly advised | Your HTTPS endpoint for uninstall notifications. Without it you never learn that a merchant removed you. |
webhook_uri | No | A destination for data webhooks. On every install Bito automatically subscribes it to create/update/delete on a fixed set of collections. You can also register destinations over the API — see data webhooks. |
iframe.url | For widgets | The page Bito embeds in your integration's settings tab, authenticated with a one-time token. This is not how a custom widget works. |
ip_whitelist | No | An allowlist of source addresses: single IPv4 addresses or CIDR subnets, at most 50. While it is empty, the keys are accepted from any address; once it is filled, an Integration API request from any other address is refused with 403. Edit it in the form's IP whitelist field; for a developer app, under My apps → app → Keys → Allowed IP addresses. |
duplicate_control | No | Whether Bito should apply duplicate control to records this integration creates. |
multiple_sources | No | Whether this integration works alongside other sources of the same data. |
WARNING
All URLs must be https:// and publicly reachable. Bito refuses loopback, private-network and cloud-metadata addresses, and URLs that carry credentials.
3. Save and copy the keys
Press Save. The Integration created dialog shows client_id, secret and api_key — the secret is never shown anywhere again. See Your credentials.
4. Install it
A new integration is not installed, and every API call made with its keys fails with Integration is not installed. Open it from the Installed list on the Integration page and press Install. Installing sends the install hook and creates the webhook_uri subscription.