Authentication & Tokens

Every API request, except the two documentation endpoints, is authenticated with a personal access token sent as a Bearer credential.

Sending a token

GET /api/v1/organization HTTP/1.1
Host: app.bookyourpto.com
Authorization: Bearer pat_...

• The scheme is Bearer (case-insensitive), followed by one space and the token.
• Send the token on every request. There are no sessions or cookies.
• Never put a token in a URL or query string.

GET /api/v1/openapi.json and GET /api/v1/postman.json need no token. See Postman & OpenAPI.

Token format

pat_<43 characters>_<6 characters>

A complete token is 54 characters long. The first 12 characters (for example pat_Xy3kQ9Lm) are its prefix, shown in the token list so you can tell tokens apart without exposing them.

BookYourPTO stores only a keyed hash of each token, never the token itself. That is why a token is shown once, when it is created, and can never be displayed again.

Expiry

Every token expires. There is no "never expires" option.

• When you create a token you choose a lifetime preset (7, 30, 60, 90, 180 or 365 days) or a specific date. Presets longer than your organization's maximum are not offered.
• A specific date means the end of that day in your timezone.
• The organization's maximum token lifetime is set by an Executive, from 1 to 365 days, and defaults to 90. Lowering it applies to tokens created afterwards; existing tokens keep their expiry.
• The token's owner is emailed once, seven days before the token expires.
• After it expires the token is refused with 401 AUTH_INVALID. Create a new token, or rotate it before it expires.

Rotating a token

Rotation issues a new secret for the same token configuration and retires the old secret after a grace period, so you can deploy the new secret without downtime.

1. In Settings > API, open the token's menu and choose Rotate.
2. Pick a grace period: 0, 1, 24 or 72 hours.
3. Copy the new token, which is shown once.

The replacement keeps the name, owner, API role or scopes, and IP allowlist. Its expiry defaults to the old token's, capped at your organization's maximum lifetime counted from now; you can choose a new expiry while rotating. A token can be rotated only once; to rotate again, rotate its replacement.

Revoking a token

Revoke a token the moment you suspect it has leaked, or when the integration using it is retired.

1. Open the token's menu and choose Revoke.
2. Enter a reason (required, up to 500 characters). It is kept in the audit log.

Revocation takes effect on the next request. It works even when the API is switched off or the plan no longer includes API access, so a leaked token can always be stopped. Revoked tokens are kept in the list as a record and can be shown with the All, including revoked and expired filter; they are never deleted.

Administrators and Executives can see and revoke every token in the organization. Other people who are allowed to create tokens see and manage only their own.

Changing a token

Without reissuing the secret, you can change a token's name, its IP allowlist, its API role or custom scopes, and (Administrators and Executives only) transfer it to a different owner. Because a token acts as its owner, a transfer changes what the token can see, and it is refused unless the new owner could use the token right now and may hold every scope it grants.

An Administrator cannot change or rotate a token owned by an Executive. A transfer is also refused if the token's secret holder would no longer rank above the new owner. Anyone who can see a token can revoke it.

Owner and secret holder

Two people matter for every token:

• The owner is the person the token acts as. Their role and visibility decide what it can see and do.
• The secret holder is the person who received the token's secret when it was created or last rotated. Usually this is the owner.

When you create or rotate a token for someone else, you become its secret holder. That is only allowed when the owner's role is below yours: an Administrator can create a token owned by an Employee or a Department Head, but not by another Administrator or an Executive. People in the same role create their own tokens.

The secret holder is checked on every request just like the owner. If the holder leaves, is deactivated, or no longer ranks above the owner, the token stops working, because the person holding its secret should no longer be able to act as the owner. Rotating the token issues a new secret to whoever rotates it, who becomes the new secret holder.

IP allowlists

Each token can optionally be restricted to a list of addresses:

• Up to 50 entries, each an IPv4 or IPv6 address or a CIDR range (for example 203.0.113.10 or 198.51.100.0/24).
• An empty list allows any address.
• A request from any other address is refused with 403 IP_NOT_ALLOWED.

Use an allowlist whenever your integration runs from fixed egress addresses, such as a server with a static IP or an integration platform that publishes its outbound ranges.

When a token stops working

A token is checked from scratch on every request; nothing is cached between requests. It stops working as soon as any of these is true:

Every 401 uses the same message whatever the cause, so a response never reveals whether a token exists. If a token that worked yesterday now returns 401, check its status in Settings > API and its owner's account.

Deactivation revokes tokens permanently

When a person is offboarded, or their personal data is deleted, every token they own, and every token whose secret was issued to them, is revoked at the same moment their account is deactivated, and every webhook endpoint they own is turned off. Reactivating the person later does not bring those tokens back: issue new ones. Revoked tokens stay listed in Settings > API with the reason, as a record.

Demotion

When a person's role is lowered:

• Their own tokens follow their new role from the next request. If the new role may still hold tokens, each token keeps working but loses every scope above the new role. If it may not, the token is refused until their role allows it again.
• Secrets they hold for someone else, from creating or rotating a token owned by a person below them, are revoked permanently. A later promotion does not bring them back.

Failed authentication from a shared address

Repeated failed authentication from one address is blocked: after more than 20 failed attempts within 10 minutes, that address is refused for 15 minutes. The block only refuses requests that fail authentication. A request with a valid token is never locked out by someone else's failures, so integrations running on a shared address, such as an integration platform, a corporate network or a CI service, keep working while another client there misbehaves. See Rate Limits.

Storing tokens safely

• Keep tokens in a secret manager or your platform's encrypted environment variables, never in source code, spreadsheets, tickets or chat.
• Use one token per integration, so you can revoke one without breaking the others, and so the activity log shows which integration made each request.
• Grant the fewest scopes that work, and add an IP allowlist where you can.
• Choose the shortest expiry your process can support, and rotate before expiry rather than creating long-lived tokens.
• Never call the API from a browser or a mobile app you distribute: anyone could extract the token from it.
• If a token appears anywhere it should not, revoke it first and investigate second.