Authentication

The Trybe API authenticates server-to-server requests with a long-lived personal access token (PAT) sent as a Bearer token in the Authorization header. End-user sessions for customers, guests and members go through a separate OAuth 2.0 + OpenID Connect flow — see Single Sign On. This page covers the PAT flow.

The header

Every request needs an Authorization header in this exact shape:

Authorization: Bearer YOUR_API_KEY

The Bearer prefix (with the trailing space) is mandatory. The token itself is opaque; don't try to parse or split it.

curl https://api.try.be/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

In code, set the header once on a shared HTTP client rather than copying it onto every call.

// Node / fetch
const trybe = (path, init = {}) =>
  fetch(`https://api.try.be${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRYBE_API_KEY}`,
      Accept: 'application/json',
      'Content-Type': 'application/json',
      ...init.headers,
    },
  })

const res = await trybe('/sites')
const { data } = await res.json()

// PHP / Guzzle
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.try.be',
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('TRYBE_API_KEY'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->get('/sites');
$body = json_decode((string) $response->getBody(), true);

Getting a token

Personal access tokens are issued out-of-band by the Trybe team. Contact your Onboarding Manager with:

• The email address of the Trybe user the token should belong to.
• The environment(s) you need: playground, production, or both.
• A short description of what the integration does.

You'll receive one token per environment. Tokens are tied to a real user and inherit that user's permissions on each site — so if the user can't manage appointments on a given site, neither can the token. Issue tokens to a dedicated integration user rather than a personal account; it makes audit trails and access changes easier later on.

Tokens, users, and site access

A few conventions to know before you ask for production access:

• A token is bound to a user, not to an integration. Permissions resolve against that user's site-level role at request time. Change the role, and the token's effective access changes immediately — no token re-issue needed.
• A user can have access to one or more sites. When you request a token, list every site the integration needs to call against; if access is added later, the same token picks it up automatically.
• One integration user per integration. Don't share an integration user across two unrelated systems — the moment one needs a permission change, the other inherits it. Audit logs are also keyed on the user, so per-integration users keep the trail clean.
• Test and production are separate tenants with separate users. Your playground user and production user are unrelated records; the tokens issued against them are unrelated bearer strings. Use distinct env vars (e.g. TRYBE_API_KEY_PLAYGROUND / TRYBE_API_KEY_PROD) so a config error can't cross-fire.
• Production tokens require site-manager approval. When you ask for a production key, name every site you need access to. The site manager for each site authorises the issuance via email; your Onboarding Manager handles the coordination but can't bypass the approval.

The standard role covers what most integrations need (read + mutate against the integrator's own data). Higher-privilege roles (manager, owner) are reserved for back-office tooling. If you think you need a non-standard role, talk it through with your Onboarding Manager first — most use cases turn out to be doable with standard plus a specific site grant.

What Trybe auth is NOT

A common ask we hear from integrators with multi-tenant experience:

• Trybe is not an OAuth 2.0 identity provider for partner apps. There's no client-credentials grant, no scopes parameter on the token, no machine-to-machine OAuth dance. If you need to sign Trybe customers (not your own staff) into your own app, use the customer SSO flow described in SSO.
• There's no token introspection endpoint with scopes. The closest is GET /token-info which returns the underlying JWT claims (sub, aud, exp, …). Permissions live on the user, not on the token.
• There's no per-call scope down-scoping. A token has the full permission surface of its user. If you want narrower access for a specific job, issue a token against a more-limited user.

PAT versus customer SSO

The PAT flow and the OAuth/OIDC flow solve different problems. Use the right one.

If you're building anything that runs in a customer's browser, do not embed a PAT in it. PATs are server credentials and grant broad access; leaking one is a production incident.

Transport

All requests must be made over HTTPS. Plain-HTTP requests are rejected before they reach authentication. There is no IP allowlisting; the token is the only thing that grants access, so protect it accordingly — environment variables or a secrets manager, never source control.

When auth fails

A request with a missing, malformed or invalid token returns HTTP 401 with this body:

{
  "message": "Unauthenticated"
}

A request with a valid token that doesn't have permission for the action returns HTTP 403:

{
  "message": "This action is unauthorized."
}

See errors for the full set of error shapes.

Common pitfalls

• Missing the Bearer prefix. Authorization: YOUR_API_KEY returns 401. Always send Authorization: Bearer YOUR_API_KEY.
• Whitespace or newlines in the token. Tokens copied from emails sometimes arrive with a trailing newline. Trim before use.
• Using a playground token against production (or vice versa). Tokens are environment-scoped. A token from playground does nothing against api.try.be.
• Expecting permissions to follow the org. Permissions are per-site. A user added to a brand isn't automatically added to a new site under that brand. If you start getting 403s after onboarding a new venue, check that the integration user has been granted access.
• Logging the header. It's tempting to log full requests for debugging. Redact Authorization before anything hits a log aggregator.
• Storing the token in a frontend bundle. Use the SSO flow for end-user contexts instead.

Revoking a token

If a token leaks, contact your Onboarding Manager immediately and request a rotation. There is no self-service revocation today; the team will issue a replacement and disable the old one.