Summary of the change
We've replaced our legacy API key system with Personal Access Tokens (PATs). PATs are the single way to authenticate non-agentic integrations going forward, SCIM identity-provider sync, Digital Signage TVs, and direct calls to the Bonusly REST API all run on the same token type.
The legacy "API Keys" screen is still visible for now in a read-only mode (so existing integrations keep working), and we'll migrate every active legacy API key to a PAT for you in the week following this release. That migration is invisible to your integrations — the same bearer string keeps working. The only thing customers need to track is that PATs expire (max one year), so a year from migration you'll be prompted to mint a fresh token if you want the integration to keep running.
A new admin surface sits at Company → Integrations → API & Tokens. That tile is the home for Bonusly API, SCIM, and Atom feed setup. The Digital Signage and SCIM pages still exist under their own tiles, but both are now built around PATs.
Who can do this
Personal Access Tokens are minted from your own admin account. Two permission levels can mint tokens:
Global admin — can mint a token with any scope.
Tech admin — can mint tokens that read or write company data including
user:administerfor SCIM. Some scopes (finance:administer,awards:administer, etc.) are reserved for Global admins.
You can find your admin level under your profile menu. Regular users do not have access to the new API & Tokens page.
What's different from the old API keys
| Old API Keys | Personal Access Tokens |
Expiration | Never expired | You pick, up to 1 year |
Permissions | A single "read-only" flag | Fine-grained scopes (read / write / administer per resource) |
Audit | Last-used timestamp only | Last used, expiration reminders, sign-in log entries with IP, scope info |
Revocation | Manual, all-or-nothing per key | Per-token revoke; auto-revoked 7 days after a company cancels |
Visibility | Whole-company table | Per-admin view + a global table for admins |
The practical advice: mint a separate token per integration. If a vendor changes or a key gets exposed, you can revoke that one token without touching the others.
Where to find the admin page
Sign in as a Global or Tech admin.
Go to Company → Integrations.
Click the API & Tokens tile.
From this page you can:
Create a new Personal Access Token (the Create token button).
See every PAT that has been minted for your company, who owns it, when it was last used, and when it expires.
Revoke a token immediately.
Find the Atom feed URL (further down the page, with a copy-to-clipboard button — Atom now uses a PAT instead of an API key).
Find a quick link out to docs.bonus.ly for the full Bonusly API reference and an explanation of MCP.
The SCIM and Digital Signage tiles in Company → Integrations each have their own dedicated screens; both are now built around PATs too (see the sections below).
Creating a Personal Access Token
On the API & Tokens page, click Create token. You'll be asked for:
Name — a free-text label so you can identify the token later (e.g. "Snowflake nightly ETL", "Make.com — Slack birthday workflow").
Expiration — a number of days, up to 365. Tokens cannot live longer than a year; this is enforced.
Scopes — the set of permissions this token will carry. Only scopes your admin role is authorized to grant will appear in the list. (Example: a Tech admin minting a SCIM token can grant
user:administer. A Global admin sees the full catalog.)
After you click Create, Bonusly shows the token string once. Copy it into your integration's configuration before closing the dialog — the plaintext is not retrievable afterwards. We store only a hash; if you lose the token you'll need to mint a new one.
Using a Personal Access Token
A PAT is a bearer token. Pass it on every API request in the Authorization header:
GET https://bonus.ly/api/v1/users/me
Authorization: Bearer <your-token-here>
The token works against:
The legacy REST API at
https://bonus.ly/api/v1/*.The new public API at
https://bonus.ly/api/public/*(per-scope enforcement applies).The SCIM endpoint at
https://bonus.ly/scim/v2/*(token must haveuser:administer).The Atom feed endpoint linked from the API & Tokens page.
If your integration only supports an access_token query parameter instead of a header, that works too: https://bonus.ly/api/v1/users/me?access_token=<token>. We recommend the header form because query parameters can leak into server logs.
Expiration and renewal
Every PAT expires. We'll email the token owner (the admin who minted it) twice before expiry:
30 days out — a heads-up so you can plan a renewal.
7 days out — a final reminder.
When the token expires it stops working. To renew:
Visit Company → Integrations → API & Tokens.
Mint a fresh token with the same scopes (use the existing token's name as a reference).
Update the integration's stored credential with the new token.
Revoke the old (now-expired) token's row to keep the table tidy.
There's no auto-rotation; renewals are deliberate.
SCIM (identity-provider sync)
Customers connecting Okta, Microsoft Entra (Azure AD), or another SCIM-capable IdP to Bonusly should follow this flow on the new SCIM admin page:
Company → Integrations → SCIM.
Click Connect SCIM.
Enter a name (e.g. "Okta production"). Bonusly mints a PAT with
user:administerscope on your behalf and shows you the bearer once.Copy the bearer into your IdP's SCIM configuration along with the SCIM base URL shown on the page.
Multiple SCIM tokens per company are supported (one per IdP if you have more than one source of truth). To rotate, mint a new token, update the IdP, and then revoke the old one.
Digital Signage
The Digital Signage TV setup flow now also uses PATs. The admin workflow:
Company → Integrations → Digital Signage.
Click Add screen (or "Connect a TV") and give it a name.
Bonusly mints a Digital Signage PAT and produces a setup URL pre-loaded with the bearer.
Open that URL on the kiosk display. The TV stores the bearer in a cookie and starts polling for bonus data.
PATs minted for Digital Signage have limited scope and a debounced last-used timestamp so the admin page can show which screens are actually polling.
Existing screens running on a legacy API key will continue to work. On their next reload, Bonusly silently exchanges the legacy bearer for a new Digital Signage PAT and continues without any human action. You'll see new PATs appear in your list as that happens.
What happens at the end of a subscription
If a Bonusly subscription is canceled, we leave PATs alone for seven days long enough for the company to come back if it was a mistake or a delayed renewal. Seven days after a cancellation that hasn't been reversed, Bonusly automatically revokes every active PAT in the company silently (no email).
If the company resubscribes inside that 7-day window, nothing happens to the tokens.
If the company resubscribes after revocation, the integrations won't auto-recover admins will need to mint fresh tokens from the API & Tokens page.
Existing API keys
You don't need to do anything. Here's the timeline:
Today — the old API Keys table is read-only. Existing keys keep working.
This week — we'll migrate every active legacy API key to a matching PAT. The bearer string customers already have keeps working; nothing has to change on the integration side.
One year from migration — the migrated PATs will hit their expiration. The 30-day and 7-day reminder emails will fire just like for any other PAT. Mint a replacement and update the integration.
Later — once usage of the read-only API Keys table reaches zero, that page will be removed
FAQs
Can a regular (non-admin) user mint a token? Not for company-wide integrations. The API & Tokens admin page is visible only to Global and Tech admins. A future iteration will expose self-scoped PATs to regular users so they can call the API on their own behalf for personal automation.
What scopes does a Bonusly token support? The full catalog is at https://docs.bonus.ly/reference/intro/getting-started. The most common scopes:
user:read,user:write,user:administer(the last is required for SCIM)recognition:read,recognition:write,recognition:administerawards:read,awards:write,awards:administerfinance:administercompany:read,company:administeranalytics:readuploads:write
When you mint a token, Bonusly hides any scope your admin role can't grant.
Can I see who minted which token? Yes — the API & Tokens page shows the owner of each token. The sign-in log under Admin → Security also shows each token's IP and user agent on first use per day.
What if a token is leaked? Revoke it immediately from the API & Tokens page. Revocation is instantaneous. Mint a new token, update the integration with the new bearer.
Does the MCP server use the same tokens? No — Bonusly's MCP server uses OAuth (the same authentication mechanism your favorite AI client uses to talk to other SaaS apps). PATs and OAuth tokens are both stored alongside each other in Bonusly, but you'll authorize MCP through the OAuth consent flow, not by pasting a token.
Questions? Send us a note to [email protected]; we'd be happy to help!
Was this article helpful? Let us know by rating it below with an emoji and sharing your feedback!