Bots & API Tokens

A bot is a named machine identity with its own API token. Use one when a script, a CI job, or another system needs to talk to the SkySaver API — updating schedules, pulling reports, or triggering automations — without a person signing in.

A bot counts as a member of your project. It appears in the Users tab alongside people, labelled BOT, and carries its own set of permissions.

Prerequisites

The create:bot_tokens permission to create a bot
The manage:bot_tokens permission to change a bot’s permissions
The generate:bot_tokens permission to issue a replacement token
The delete:bot_tokens permission to remove a bot

Creating a bot

Go to Tenant Management → Bots.
Click Create Bot.
Give it a name that says what it does — the name appears in the Users list, so ci-deploy is more useful than bot1.
Select the permissions it needs. Grant the narrowest set that works: a bot that only reads reports has no reason to hold write:schedules.
Click Create Bot.

The token is displayed once, immediately after creation. Copy it then and store it somewhere your scripts can read it — a CI secret, a password manager, a secrets store. SkySaver keeps only a hash of the token, so it cannot be shown again. If you lose it, generate a new one.

Using a token

Send the token in the Authorization header:

curl -H "Authorization: Bearer sks_..." \
  https://api.skysaver.io/api/project/<projectId>/schedules

Unlike the web app, no Identity header is required — the bot token is the whole credential.

To check what a token can do, ask the API:

curl -H "Authorization: Bearer sks_..." \
  https://api.skysaver.io/api/user/project/<projectId>/scopes

Token lifetime

Bot tokens do not expire. They stay valid until you replace or delete them.

Use Generate New Token to rotate one — after a suspected leak, when someone with access leaves, or on whatever cadence your policy requires. Rotation issues a new token and revokes the old one, so update everything using it first. Revocation can take up to five minutes to take full effect, because permission decisions are briefly cached.

What bots cannot do

Bots are barred from tenant administration. These permissions are never offered when editing a bot, and are rejected if requested directly:

Permission	Why
`org:poweruser`	Grants everything — defeats the point of scoping a token
`manage:project`	Project settings and SSO configuration are people decisions
`read:project_members`, `write:project_members`, `manage:project_members`, `delete:project_members`	A bot must not be able to read, add, or re-permission members
`read:bot_tokens`, `create:bot_tokens`, `manage:bot_tokens`, `generate:bot_tokens`, `delete:bot_tokens`	Stops a leaked token from minting persistent replacements

A bot is also bound to the project it was created in. Its token cannot read or write any other project, even one the person who created it belongs to.

Managing an existing bot

Change permissions — edit the bot from either the Bots tab or the Users tab; both open the same dialog. Requires manage:bot_tokens.
Generate a new token — from the bot’s action menu. Requires generate:bot_tokens.
Delete — removes the bot from the project and revokes its token. Requires delete:bot_tokens.

Bots cannot be edited or removed through the ordinary member controls, because doing so would bypass the permission rules above and could leave a live token with no owner.

Good practice

One bot per job. Separate tokens for separate systems mean you can rotate or revoke one without disrupting the rest, and the Users list tells you who did what.
Grant the minimum. Start with read-only and add permissions when something actually fails.
Never commit a token. Treat it like a password: CI secret store, environment variable, or a secrets manager.
Watch “Last used”. A bot that has not been used in months is a credential you can delete. The column updates once a day.