FAQ & troubleshooting

Credentials

I lost my client secret. Can I read it again?

No. It is shown once, at creation. Rotate it to get a new one — but understand that rotation disconnects every merchant currently connected to your integration, in every account.

Do my credentials change when Bito approves my integration?

No. Approval does not touch credentials. Visibility, too, changes only on card approval — PRIVATE becomes PUBLIC. Approving a release makes its code runnable but does not make the app public.

client_id never changes. secret and api_key change only when you rotate them yourself: Reissue keys in the panel replaces both in one call; there is no panel button for the API key alone — that is done over the API with regenerate_api_key: true. See Rotating credentials.

What is the app or integration code?

A permanent public slug stored as system_id in the API. In My apps you choose it, check availability and claim it before publication. It is Bito's equivalent of an amoCRM widget code; it cannot be renamed after it is saved. It is also the {widget_code} in left-menu URLs and the value of bito.widget.code.

Can I use one integration for several merchants with just the API key?

No. An api_key belongs to one account. Serving many merchants means OAuth, where each install has its own token pair.

Authentication

Integration is not installed on every call

A new integration is created uninstalled. Open it from the Installed list on the Integration page and press Install — see Create an integration. The same error comes back after a merchant uninstalls the integration.

403 with You don't have permission to access from this IP

The integration has an ip_whitelist and the request came from an address that is not on it. Add your server's address (IPv4 or CIDR) or clear the list — see Create an integration.

401 Unauthorized on every call

Check, in this order: the header name (api-key for the key path, Authorization: Bearer … for OAuth), that the key includes the username: prefix, and that the access token is under 24 hours old.

My access token suddenly stopped working before 24 hours

Something terminated the session behind it. The usual cause is a secret rotation; a merchant uninstalling you is the other. Re-authorize.

Invalid credentials when exchanging the authorization code

Either the code was already used, or it is older than 20 minutes, or the client_secret does not match. Codes are single-use — restart the flow to get a fresh one.

Refresh fails with Invalid credentials

Refresh tokens rotate on every use. If you kept the old one after a successful refresh, it is dead. Persist the new pair in the same transaction that consumes the old one.

Webhooks

I subscribed but nothing arrives

Check that your destination is https://, publicly reachable, and not on a private network — Bito refuses loopback, RFC1918, link-local and cloud-metadata addresses. Then check whether the change you are testing came from a bulk operation: mass imports and bulk updates emit no webhooks at all.

The signature never matches

You are almost certainly hashing a re-serialized body. Compute the HMAC over the raw request bytes, before any JSON.parse. The key is your client secret (client_secret); if you rotated it, use the new one. See verifying the signature.

An event was delivered twice / out of order / not at all

All three are possible by design. Delivery is single-attempt, unordered, and never retried. Treat a webhook as a hint to re-fetch the record, and reconcile periodically with a full read.

My integration was uninstalled and my webhooks stopped

Uninstalling deletes every webhook the integration owns. Re-installing re-creates the webhook_uri subscription automatically; destinations added with webhook/subscribe must be subscribed again. The signing secret does not change: it is your client secret (client_secret), and it changes only when you rotate it.

Publication

How long does review take, and what is checked?

Bito reviews the marketplace card and a widget release separately. It checks the listing, permissions, public HTTPS lifecycle URLs, archive and manifest, declared surfaces, install/uninstall behavior and the real in-product test path. A release passes three ordered stages — code, listing and usability. See Submit for review and Review & publication.

My submission was rejected

First check which track was rejected. A card rejection appears in General info; a release rejection appears on that version in Versions. Fix and resubmit only that track. The public card and an open release do not share one status.

My release is approved. Why is the app not in the marketplace?

Release approval makes the code runnable; it does not approve the marketplace card. Submit the card from General info. For a widget app, card publication also verifies that the current release was moderator-approved rather than only activated locally.

Does approval install my integration for everyone?

No. Approval only lists it in the marketplace. Each merchant still installs it themselves, and each install triggers your install hook.

API behaviour

Why are list endpoints POST rather than GET?

Because their filters are a JSON body, not a query string — paging, date ranges and nested filters do not fit comfortably in a URL. Single-record reads are GET, updates are PUT, deletes are DELETE. The method table has the full picture.

Note that the Bito admin API (what the web panel uses) is POST-only. That rule does not apply here.

I deleted a record but it still comes back

Bito soft-deletes. The record is flagged, not removed, and most resources have a get-deleted endpoint. Filter on your side if you need only live rows.

How do I sync only what changed?

Most get-paging endpoints accept an updated_at filter. Store the timestamp of your last sync and pass it — this is much cheaper than paging the whole collection.

Are writes idempotent?

No. A repeated create creates a second record. Deduplicate on your side before retrying a write.

Still stuck? Contact support.