Authentication

Every request carries two things:

Authorization: Bearer <access token>
x-property-id: <property id>

Operations performed on behalf of a person, such as creating an order or taking a
payment, also carry that person's staff token:

X-Staff-Token: <staff token>

Each operation's reference page lists which of these it needs.

Access tokens

The API accepts two kinds of bearer token.

Cloudbeds user access token

This is the same OAuth access token the rest of the Cloudbeds API uses. Send the
property you are acting on in x-property-id. It must be one of the properties
in the token, or the request returns 403.

POS device token

A terminal becomes a device by pairing with the property:

1. In Cloudbeds, an administrator registers the device for the property and gets
   a short, single-use enrollment code.
2. The terminal generates a key pair, claims the enrollment code with its public
   key, and receives a device id.
3. The terminal then requests access tokens from the Cloudbeds authorization
   server, signing each request with its private key (OAuth 2.0 client
   credentials with private_key_jwt).

A device token names the properties the device is paired to. If it names exactly
one, x-property-id can be omitted. Otherwise it is required, and it must be one
of those properties.

Staff tokens

POS terminals are shared, so the person using one signs in with a PIN:

POST /pos/auth/staff/login
Authorization: Bearer <device token>
x-property-id: 12345

{ "pin": "4821" }

{
  "staff_token": "eyJhbGciOi…",
  "staff": {
    "id": "3d0b6c2e-8f4a-4b1d-9e7c-5a2f1d8b6c40",
    "name": "Ana Lima",
    "role_id": "b71e9a04-2c5d-4f3e-8a6b-9d0c1e2f3a45",
    "property_id": "12345"
  }
}

• PINs are unique per property, so the PIN alone identifies the person. Send
  staff_id as well when you already know who is signing in.
• A wrong or unknown PIN returns 401. After repeated failures the device is
  locked for a few minutes and gets 429.
• Staff tokens expire after a fixed number of hours. POST /pos/auth/staff/logout
  ends the session; discard the token either way.
• The staff token and the access token must belong to the same property.

After sign-in, GET /pos/staff/{staff_id}/outlets lists where the person works,
and GET /pos/staff/{staff_id}/permissions lists the permission codes their role
grants. Use the codes to decide which actions to offer.

Approvals

Some actions need a permission the signed-in person may not have, such as a
discount above the outlet's cap, voiding an item already sent to the kitchen, or
a refund. A colleague who has the permission can approve the action on the spot:

POST /pos/auth/approve
Authorization: Bearer <device token>
X-Staff-Token: <requesting staff token>

{
  "approval_pin": "7302",
  "action": "void_sent_item",
  "subject_id": "0c9a3f8e-5b1d-4e8a-9f0b-6a2d7c4e1b55"
}

The approver types their own login PIN. If their role grants what action
requires, the response carries an approval_token. Pass it on the operation that
performs the action, for example POST /pos/orders/{order_id}/void-item/{item_id}.

An approval token:

• is single-use;
• expires after a couple of minutes, or 15 minutes for a discount approved on a
  cart that has not been saved yet;
• only works for that action and that subject_id (an order, or an order item).

The approver is recorded on the result.