Skip to content

Authentication

This page is the overview for all supported ways to call the Partners API (/api/v1/*). Step-by-step curl examples live in the audience guides linked below.

New here? Start at For Partners or For Personal Users, then return here when you need the full mechanism reference.

Choose The Right Mechanism

Who you are What you should use Why
Partner or company integrating many customers on a secure backend OAuth2 client credentials with a confidential client Strongest option: client secret never ships to end-user devices, machine-to-machine access, optional per-user and per-credential narrowing with user_id and credential_id.
Individual Beyond user automating your own account (CLI, script, agent) Personal access token (PAT) A PAT is a long-lived, credential-scoped secret you create yourself from the Beyond dashboard. No client secret to manage, no browser step at runtime; ideal for non-interactive automation on your own account.

Partners should not rely on PATs for production integrations: PATs exist only for personal automation applications, not partner multi-tenant apps.

For the personal access token walkthrough, use For Personal Users. For partner token requests with user_id / credential_id, use For Partners.

On every /api/v1/* request, send the access token or PAT in the header Authorization: Bearer <token>.

OAuth2: Client Credentials (Confidential Partner)

Typical path: your backend exchanges client_id and client_secret for an access token, then calls /api/v1/*. Optional user_id and credential_id narrow the token (see For Partners).

sequenceDiagram
    participant Partner as PartnerBackend
    participant Token as OAuthTokenEndpoint
    participant API as PartnersAPI

    Partner->>Token: POST /o/token/ client_credentials
    Note right of Partner: client_id, client_secret, scope optional user_id credential_id
    Token-->>Partner: access_token, expires_in, token_type Bearer
    Partner->>API: GET /api/v1/... with Authorization Bearer
    API-->>Partner: JSON API response

Shared OAuth2 Rules

The Partners API follows RFC 9700 - OAuth 2.0 Security Best Current Practice.

Token Lifetimes

  • OAuth2 access tokens (client credentials) expire after 1 hour.
  • Personal access tokens do not expire until revoked.

Grant Restrictions

Grant Type Status Notes
Client Credentials Allowed For partner server integrations
Implicit Disabled Rejected
Password Disabled Rejected

User-Scoped Tokens

Server integrations can ask /o/token/ for either an application-level token or a user-scoped token:

  • Application-level token: omit user_id. The token acts for the OAuth application and can access all users owned by that application, subject to the scopes granted on the token.
  • User-scoped token: include user_id. The token is bound to that one user. You may also include credential_id to apply one Beyond login's visibility and permissions; without it, Beyond uses the user's primary credential.

If Beyond enables require_user_scoped_tokens for your application, user-level resource scopes cannot be used on an application-level token. You must include user_id for those scopes. App-level scopes and cross-tier scopes still work without user_id.

Scope Tiers

All requested scopes must first be enabled for your OAuth application. After that, token tier rules apply:

Tier Scopes Application-level token, no user_id User-scoped token, with user_id
App-level user:write Allowed. Operates on the application as a whole. Rejected. App-level scopes cannot be combined with user_id.
User-level listings:read, listings:write, reservations:read, accounts:read, insights:read Allowed only when require_user_scoped_tokens is disabled for the application. Rejected when it is enabled. Allowed. Access is limited to the bound user, and to the selected credential when credential_id is present.
Cross-tier user:read Allowed. Returns users owned by the application. Allowed. Returns only the bound user.

Scope Reference

Scope Tier Description
user:write App-level Create and modify users
user:read Cross-tier Read user information
listings:read User-level Read listing data
listings:write User-level Modify listings
reservations:read User-level Read reservation data
accounts:read User-level Read account information
insights:read User-level Read market insights

IP Allowlist

When configured for an application, IP allowlists are enforced on both /o/ and /api/v1/.

Personal Access Token (PAT)

PATs are not an OAuth2 grant. Beyond users can create and manage their own PATs from the Beyond dashboard user settings when they need a long-lived credential for personal automation. Beyond shows the secret exactly once at creation time; after that, each request uses Authorization: Bearer with the PAT. Store it like any other high-value credential. A PAT inherits the permissions of the Beyond login (credential) it was issued for: what listings and accounts the token can read and write follows that credential's configuration on the Settings / Team page, and permission changes there apply to the token immediately. IP restrictions, when Beyond has configured them for the app, are enforced the same way as for OAuth2 access tokens.

sequenceDiagram
    participant Client as AutomationClient
    participant API as PartnersAPI

    Client->>API: Authorized request with Bearer PAT
    API-->>Client: JSON API response

Use your issued cleartext value in the Authorization header. Personal access tokens always start with the bpat_ prefix.

PAT Rules (Summary)

  • Personal automation only — PATs are for personal automation apps (one Beyond user), not for partner-style multi-customer integrations.
  • One login — A PAT only ever acts as the Beyond login (credential) it was issued for. It cannot switch to another login under the same user.
  • Self-service creation — PATs are created from the Beyond dashboard, not minted through /o/token/.
  • Permissions follow the credential — A PAT acts with the permissions of its credential. Manage what the token can read and write through that credential on the Settings / Team page; changes apply immediately.
  • No OAuth minting — PATs are not created or refreshed through /o/token/. They are created and revoked from the Beyond dashboard.