Start Here: Use This Section When #
- You need to connect WordPress, WooCommerce, PrestaShop, Shopify, or another external system.
- A token was lost, rotated, revoked, or needs replacement.
- An integration is failing with
401,403, or signature-related errors.
Prerequisites #
- CompanyAdmin role.
- A subscription plan that includes external integrations / API access.
If your plan does not include it, the Add New Token button is disabled and a yellow notice says Token management is unavailable on your current plan. with the reason "The current subscription package does not include external integrations API access." Upgrade your plan to unlock it.
Create a New Token #
- Open Settings → Company Settings → Third-Party Tokens (use the Integration tokens shortcut at the top).
- Click Add New Token. A window opens.
- Fill in the form:
| Field | What to enter | Rules |
|---|---|---|
| Token Name | A clear label, e.g. WordPress Storefront | Required, up to 200 characters |
| Third-Party URL | The site that will use the token, e.g. https://store.example.com | Optional, must be a valid URL, up to 256 characters |
| Description | A note about where it is used | Optional, up to 500 characters |
| Expires At (UTC) | A date and time after which the token stops working | Optional. Note: UTC time, not your local time. Leave empty for no expiry. |
| Scopes | Tick what the token is allowed to do | Choices: All scopes, Contacts: Read, Contacts: Write, Campaigns: Read, Campaigns: Write, Templates: Read, Workflows: Read, Integrations: Events Write, Integrations: Events Read. If you tick none, the token has all scopes. Give each integration only what it needs. |
- Click Create Token.
- A yellow box shows the raw token. Click Copy Token and store it in your external system straight away.
Critical: the raw token is shown once. It cannot be viewed again. In the list, Copy Token is only active right after creation; afterwards it is greyed out with the hint "The raw token secret is only available immediately after creation."
If you leave the page without copying the token -> create a new token immediately -> update the external system with the replacement -> remove the lost one.
The Token List #
Columns: Name (with description), Site, Token Prefix (the first 8 characters, for recognising a token — it cannot be used to sign in), Scopes (All scopes when none were chosen), Status (Active / Inactive), Last Used and when it was created.
Manage Existing Tokens #
- Deactivate / Activate: click the button, confirm in the pop-up. A deactivated token stops authenticating until reactivated. Messages: "Token deactivated successfully." / "Token activated successfully." /
Unable to update token status. - Remove: click Remove and confirm. The token is permanently revoked and can never be used again. Messages: "Token removed successfully." /
Unable to remove token.
If X -> Do Y #
- If the integration says
401 Unauthorized-> verify the raw token value in the external system -> if uncertain, generate a replacement token. - If the integration says
403 Forbidden-> check whether the token is Inactive, expired, or missing the scope the call needs -> create a fresh active token with the right scopes. - If you do not know which token a site is using -> create a new token with a clear name and URL -> replace the old token in that site.
- If a site has been retired -> Remove its token instead of leaving it active.
- If Add New Token is greyed out -> your plan does not include API access (see above).
- If a token suddenly stops working on a date -> it reached its Expires At (UTC) time; create a new one.
Errors, Messages, and Exceptions #
| Message | Why It Happens | How to Fix |
|---|---|---|
The Name field is required. | Token Name left empty | Enter a name |
| Message about the URL being invalid | Third-Party URL is not a full URL | Include https:// |
| Message about a maximum length | A field is over its limit (name 200, URL 256, description 500) | Shorten it |
The current subscription package does not include external integrations API access. | Your plan has no API access | Upgrade the plan |
Unable to create token. | The server could not create it | Retry; contact support if it persists |
| Token not visible after creation | You navigated away before copying | Remove that token and create a new one |
Diagnosis Flow #
- If the external system cannot authenticate, check whether the token exists, is Active, and has not expired.
- If the token was copied long ago and you cannot verify it, replace it.
- If authentication succeeds but events still fail, move to 21. External Integrations.
