API

API Tokens & Permissions

Create a SharePush API token, choose what it can do, limit it to specific sites, and keep it safe.

API Tokens & Permissions

Every call to the SharePush API needs an API token. A token belongs to your team and to one team member, and it carries a set of permissions that decide what it can do.

#Create a token

  1. Open your profile menu → API Tokens.
  2. Click Create New Token.
  3. Give it a name that says where it's used, such as CMS production or Newsletter sync.
  4. Pick its abilities and, optionally, the sites it can access (both explained below).
  5. Create it, then copy the token right away.

The token is shown only once. SharePush stores a fingerprint of it, not the token itself, so nobody can show it to you again. If you lose it, delete it and create a new one.

#Abilities

Ability Allows
read Checking the token (/ping) and reading campaign stats.
create Creating campaigns.
update Updating a campaign, sending live updates and completing live campaigns.
delete Reserved for future endpoints. No current endpoint uses it.

New tokens get read only. To send campaigns, add create. To also send live updates, add update too.

Who can grant what: the team owner, team managers and roles allowed to manage tokens can give any ability. Other members can create read-only tokens.

#Limit a token to some sites

Under Scoped Resource Abilities you can pick individual sites and choose the abilities for each one.

  • No site selected: the token works on every site of your team, with the abilities chosen above.
  • Some sites selected: the token works only on those sites. For each call it must have the ability both at the top and on that site.

Calls about any other site are refused with 403. Scoping a token is a good idea whenever an integration only handles one site, so a leaked token can't touch the rest.

#Tokens for other team members

Owners and managers can create a token on behalf of another team member by choosing them as Token Owner. The token then acts as that member.

If the owner of a token leaves the team, the token stops working (401). Create a new one for whoever takes over the integration.

#Manage and revoke

The API Tokens page lists every token with its abilities, when it was last used and when it was created. Use Last used to spot tokens nobody uses any more.

To revoke a token, delete it. It stops working immediately. You can delete your own tokens, and owners and managers can delete any token in the team.

#Keep tokens safe

  • Use tokens only on your server. Never put one in browser JavaScript, a mobile app or a public repository: anyone who sees it can send notifications to your audience.
  • Store it in an environment variable or a secrets manager, not in your code.
  • Give each integration its own token with only the abilities it needs. Read-only dashboards need read and nothing else.
  • If a token may have leaked, delete it and create a new one.

#Your plan

API access depends on your plan. If your plan doesn't include it, every call returns 403, even with a valid token. Calls are also limited per hour. See Rate limits.

Next: REST API Reference →