Summary
Bonusly has replaced the 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.
Active legacy API keys were migrated to PATs automatically as part of the cutover. The bearer string customers already had in their integrations continues to work — no immediate action was required. The one thing to watch for is that PATs expire (max one year), so the migrated tokens will hit their expiration roughly a year after the cutover and need to be replaced.
The central admin surface lives at **Company → Integrations → API & Tokens**. It's the cross-cutting view of *every* PAT minted across your company, regardless of purpose — tokens minted from the SCIM and Digital Signage tiles also show up here, so a Global or Tech admin can see and revoke any token from one place. The SCIM and Digital Signage tiles still have their own focused setup screens, but they share the same underlying PAT model.
Who can do this
Anyone with a Bonusly account can mint a Personal Access Token — but *what the token is allowed to do* depends on the role of the person minting it:
Global admin — can mint a token with any scope, including the `administer` scopes (finance, awards, company, user, etc.).
Tech admin — can mint tokens that read or write company data, including `user:administer` for SCIM. The `finance:administer` and `awards:administer` scopes are reserved for Global admins.
Regular users- can mint tokens for their own personal automation (e.g. giving recognition from a script, pulling their own feed into another tool). They see only the scopes their role allows; the company-wide `administer` scopes aren't offered.
You can find your admin level under your profile menu. The mint surface itself also differs:
Global and Tech admins use **Company → Integrations → API & Tokens** for company-wide integration tokens.
Regular users (and admins, for tokens scoped to their own personal automation) mint tokens from their own **Settings → Services** page.
Both surfaces produce the same kind of token — the API doesn't distinguish "admin-minted" from "user-minted" PATs; what each token can do is determined entirely by its scopes.
What's different from the old API keys
| Old API Keys (retired) | 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.
What happened to your old API keys
You didn't need to do anything — Bonusly handled the migration:
Every active legacy API key was migrated to a matching PAT. The bearer string your integration already had kept working; nothing on the integration side had to change.
One year after migration, those 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.
The old API Keys admin page has been removed. All token management — for current and migrated tokens — now lives under **Company → Integrations → API & Tokens
FAQs
Can a regular (non-admin) user mint a token? Yes — from their own **Settings → Services** page. The scopes available there are filtered to whatever that user's role allows (so a non-admin can mint a token for their own personal automation, but not, say, `user:administer` or `finance:administer`). Company-wide integration tokens — anything that needs to act on data outside the user's own account — are still minted by Global or Tech admins from the **API & Tokens** page so they're owned by an admin who can rotate them.
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!