Rotating credentials

Rotating the client secret and API key

The panel has one action for rotating credentials, and it replaces both — the secret and the api_key — at once. Use it when the secret has leaked, or on a schedule if your policy requires it.

• Developer app: under My apps → app → Keys press Reissue keys and confirm with Reissue.
• Plain custom integration: in the integration's dialog press Edit, then in the Marketplace block Rotate secret → Rotate anyway.

The new secret and API key are shown right there, once — copy both immediately (in Keys, then press I saved the keys). After a page reload or closing the dialog the panel does not show them again.

Both buttons send this request.

Request

POST /admin/settings/integration/custom/regenerate-secret
Authorization: Bearer <your Bito session token>
Content-Type: application/json

{ "_id": "6712f0a9c4d1e87b3a0f1122" }

Response

{
    "code": 0,
    "message": "Success",
    "data": {
        "secret": "b81d47f2c095a6e3801fd2b7c46e9a35107fe2d84bc613905af7e28d1c60b493",
        "api_key": "acme:9f14c0f7a2b34d5e8c7190af2e5b6d3c",
        "secret_rotated_at": "2025-01-15T10:30:00.000Z",
        "api_key_rotated_at": "2025-01-15T10:30:00.000Z"
    },
    "time": "2025-01-15T10:30:00.000Z"
}

Store the new API key as well as the new secret — the old key stops working the moment this call returns.

WARNING

Rotation disconnects every merchant. The moment the new secret is issued:

• every access token issued under the old secret stops working, in every account that installed your integration — not just your own;
• every refresh token stops working, because refreshing requires the current secret;
• widget tokens signed with the old secret no longer verify;
• data webhooks and install/uninstall hooks in every account are signed with the new secret from then on. Merchants must reconnect. Treat rotation as a planned incident, not routine maintenance — deploy the new secret to your servers first, and rotate second.

Rotating only the API key

There is no panel button that rotates the API key alone. It can only be done over the API: send regenerate_api_key: true on /admin/settings/integration/custom/update. The old key stops working immediately; the secret is unchanged.

INFO

While the card is in review (pending), custom/update — including regenerate_api_key and IP allowlist edits — is refused with AlreadyInReview. Wait for the moderator's decision or withdraw the card. regenerate-secret is not subject to this.