Skip to main content

Branches in the API

API requests are always scoped to a single branch. When creating an API key, you specify which branches it can access. For each request, you can select the target branch, which determines where resources are created and accessed.

Creating API Keys with Branch Access​

When creating an API key, you can specify:

  • Branches: List of specific branches the API key can access
  • Default Branch: Default branch used when x-branch-id header is not provided
  • Is All Branches: If true, the API key has access to all branches, present and future

Selecting a Branch in API Requests​

Include the x-branch-id header to specify which branch to use for that request:

curl -X GET https://stream-app-service.streampay.sa/api/v2/user \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-branch-id: branch-uuid-here"

If x-branch-id is omitted, the API key's default_branch_id is used.

Branch Access Validation​

The API key must have access to the branch specified in x-branch-id:

  • If is_all_branches=true: Access to all organization branches
  • Otherwise: Only branches listed in branch_ids

Requests to unauthorized branches return a 4xx error.