Skip to content

Server Integrations

Use this profile for trusted backend services that can store a client secret securely.

When To Use This Path

Choose this profile if your integration:

  • Runs on your servers, workers, or scheduled jobs.
  • Needs machine-to-machine access without an end-user browser step.
  • May optionally narrow access to one Beyond user at a time with user_id.
  • May optionally narrow a user-scoped token further with credential_id.
Setting Value
App mode partner
Client type confidential
Primary grant client_credentials
Access token lifetime 1 hour
Refresh tokens Not used for client credentials

For a comparison with personal automation flows and personal access tokens, read the Authentication overview first.

Get An Access Token

Confidential clients use the client credentials grant at /o/token/ and then send the access token on /api/v1/* requests.

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

    Partner->>Token: POST /o/token/ grant_type=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/... Authorization Bearer access_token
    API-->>Partner: JSON API response
curl -X POST $BASE_URL/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=listings:read user:read"

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "listings:read user:read"
}

Optional: Narrow A Token To One User

Partner apps can request a user-scoped token by adding user_id to the token request. This is useful when your system manages multiple Beyond users and you want a token that can only act on one of them.

curl -X POST $BASE_URL/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=listings:read user:read" \
  -d "user_id=42"

The response includes user_id when the token is narrowed successfully.

Token Tiers And require_user_scoped_tokens

Beyond classifies scopes into tiers. These tiers decide whether a scope can be used on an application-level token, a user-scoped token, or both.

Tier Scopes How to request Behavior
App-level user:write Omit user_id. Operates on the application as a whole. Rejected if you include user_id.
User-level listings:read, listings:write, reservations:read, accounts:read, insights:read Include user_id when user-scoped tokens are required for your application. Acts only on the bound user's resources. If require_user_scoped_tokens is disabled, these scopes may also be used without user_id for application-level access.
Cross-tier user:read Omit or include user_id. Without user_id, reads users owned by the application. With user_id, reads only the bound user.

When require_user_scoped_tokens is enabled for your application, token requests without user_id can still use app-level and cross-tier scopes (user:write, user:read), but not user-level scopes. Requests with user_id can use user-level and cross-tier scopes, but never user:write.

Optional: Narrow A User-Scoped Token To One Credential

If you want the token to behave exactly like one login credential within the user, add credential_id. When omitted, Beyond uses the user's primary credential by default.

curl -X POST $BASE_URL/o/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=listings:read user:read" \
  -d "user_id=42" \
  -d "credential_id=314"

When credential_id is present, listing visibility and write access are constrained by that credential's global permissions and grants.

Credential-scoped visibility rules

Once a token is bound to a credential, every endpoint that supports user-scoped tokens applies the rules below. The rules are identical for listings and managed accounts: managed accounts are narrowed only when at least one of their listings would also be narrowed.

credential_id present Credential global_permissions What the token can see and do
No (app-level token) n/a All resources owned by every user of the application.
Yes ADMIN All listings and managed accounts owned by the bound user. GET /users/<id>/credentials/ returns every non-deleted credential. Can read resources and use listing write endpoints.
Yes EDIT All listings and managed accounts owned by the bound user. GET /users/<id>/credentials/ returns only the acting credential. Can read resources and use listing write endpoints.
Yes VIEW Same visibility as EDIT, but listing write endpoints return 403 Forbidden.
Yes NONE Only listings explicitly granted to the credential; managed accounts are filtered to those that own at least one granted listing. GET /users/<id>/credentials/ returns only the acting credential.

Soft-deleting a credential (for example, when a user removes a login) revokes the credential for API purposes: any token bound to it will start returning 403 Forbidden immediately, and new token requests that resolve to a soft-deleted credential are rejected at /o/token/.

Make Your First API Call

curl -X GET "$BASE_URL/api/v1/listings/?page[size]=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

Security Notes

  • Request only the scopes your integration needs.
  • If Beyond has configured an IP allowlist for your application, the same IP checks apply to both /o/* and /api/v1/*.
  • user:write is app-level only and cannot be combined with user_id.
  • When require_user_scoped_tokens is enabled, request a user-scoped token with user_id for listings:read, listings:write, reservations:read, accounts:read, and insights:read.
  • user:read is cross-tier: application-level tokens read all users owned by the app; user-scoped tokens read only the bound user.
  • User-scoped tokens inherit the selected credential's permissions. A credential with limited listing grants will see and modify only the listings it is allowed to access.

Next Steps