Set or clear a staff member's handset PIN

PUT

/v1/staff/{id}/handset-passcode

curl --request PUT \
  --url https://api.aerandil.com/v1/staff/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/handset-passcode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "passcode": "example" }'

• Production API

Validates the PIN policy (6–12 digits), hashes it (Argon2id), and records the hash on the staff_member through the internal-runner action set_staff_handset_passcode — the raw PIN never enters an action’s params, an event, or the MCP tool surface. An empty body (or passcode: null) clears the PIN. Requires actions:apply, the per-action grant for set_staff_handset_passcode, or tenant_admin:write — and, short of tenant_admin:write, the right person: a person sets their own (a desk bearer only inside a step-up window), and a manager sets a floor role’s below them at a house they share (the front office’s managers any floor role’s, a housekeeping supervisor a housekeeper’s). Nobody else sets anyone’s.

Authorizations

• aerandil_oauth

Parameters

Path Parameters

id

required

string format: uuid

The staff_member id.

Request Body

Media typeapplication/json

object

passcode

6–12 ASCII digits. Absent or null clears the PIN — the employee can no longer sign in on a handset.

string | null

/^[0-9]{6,12}$/

Example^generated

{
  "passcode": "example"
}

Responses

204

PIN recorded or cleared.

Headers

Cache-Control

string

Always no-store. Object and link state is live data and is never cacheable.

403

The bearer holds none of the accepted grants, or is not a person who may set this staff member’s PIN (step_up_required for one’s own from a desk bearer without a fresh proof).

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

404

No such staff member in the caller’s tenant.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

422

The PIN violates the policy.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}