Preference

A Preference represents a typed key-value pair owned by either a person or an organization. Preferences allow you to store and retrieve configuration data such as theme selections, locale settings, or feature flags. Each preference declares a value_type that determines how the value should be interpreted.

Sample Object

{
  "id": "pre_stu901vwx234",
  "owner_id": "ppl_abc123def456",
  "key": "theme",
  "value": "dark",
  "value_type": "STRING"
}

Fields

Field	Type	Description
`id`	`string`	Unique identifier for the preference. Auto-generated on create.
`owner_id`	`string`	ID of the person or organization that owns this preference.
`key`	`string`	Preference key used to look up the value. Must be unique per owner.
`value`	`string`	The preference value stored as a string regardless of type.
`value_type`	`enum`	Type hint for the value. One of `INTEGER`, `FLOAT`, `STRING`, `BOOLEAN`.

Actions

Person

Adding a preference

Adds a new preference to a person. The key must be unique for this owner.

obx app identity:people:preferences init
obx app identity:people:preferences push init --person-id ppl_abc123def456

POST /api/v1/identity/people/ppl_abc123def456/preferences

{
  "key": "theme",
  "value": "dark",
  "value_type": "STRING"
}

Successful response

{
  "id": "pre_stu901vwx234",
  "owner_id": "ppl_abc123def456",
  "key": "theme",
  "value": "dark",
  "value_type": "STRING"
}

Listing preferences

Returns all preferences owned by a specific person.

obx app identity:people:preferences list --person-id ppl_abc123def456

GET /api/v1/identity/people/ppl_abc123def456/preferences

Successful response

[
  {
    "id": "pre_stu901vwx234",
    "owner_id": "ppl_abc123def456",
    "key": "theme",
    "value": "dark",
    "value_type": "STRING"
  }
]

Getting a preference

Returns a specific preference by its ID within the context of the person owner.

obx app identity:people:preferences pull pre_stu901vwx234 --person-id ppl_abc123def456

GET /api/v1/identity/people/ppl_abc123def456/preferences/pre_stu901vwx234

Successful response

{
  "id": "pre_stu901vwx234",
  "owner_id": "ppl_abc123def456",
  "key": "theme",
  "value": "dark",
  "value_type": "STRING"
}

Updating a preference

Updates the value or value type of a preference. The key cannot be changed after creation.

obx app identity:people:preferences push pre_stu901vwx234 --person-id ppl_abc123def456

Deleting a preference

Removes a single preference by its ID.

obx app identity:people:preferences delete pre_stu901vwx234 --person-id ppl_abc123def456

Deleting all preferences

Removes every preference owned by the person in a single operation.

obx app identity:people:preferences delete-all --person-id ppl_abc123def456

Organization

Adding a preference

Adds a new preference to an organization. The key must be unique for this owner.

obx app identity:organizations:preferences init
obx app identity:organizations:preferences push init --org-id org_abc123def456

POST /api/v1/identity/organizations/org_abc123def456/preferences

{
  "key": "timezone",
  "value": "America/Los_Angeles",
  "value_type": "STRING"
}

Successful response

{
  "id": "pre_stu901vwx234",
  "owner_id": "org_abc123def456",
  "key": "timezone",
  "value": "America/Los_Angeles",
  "value_type": "STRING"
}

Listing preferences

Returns all preferences owned by a specific organization.

obx app identity:organizations:preferences list --org-id org_abc123def456

GET /api/v1/identity/organizations/org_abc123def456/preferences

Successful response

[
  {
    "id": "pre_stu901vwx234",
    "owner_id": "org_abc123def456",
    "key": "timezone",
    "value": "America/Los_Angeles",
    "value_type": "STRING"
  }
]

Getting a preference

Returns a specific preference by its ID within the context of the organization owner.

obx app identity:organizations:preferences pull pre_stu901vwx234 --org-id org_abc123def456

GET /api/v1/identity/organizations/org_abc123def456/preferences/pre_stu901vwx234

Successful response

{
  "id": "pre_stu901vwx234",
  "owner_id": "org_abc123def456",
  "key": "timezone",
  "value": "America/Los_Angeles",
  "value_type": "STRING"
}

Updating a preference

Updates the value or value type of an organization preference. The key cannot be changed after creation.

obx app identity:organizations:preferences push pre_stu901vwx234 --org-id org_abc123def456

Deleting a preference

Removes a single preference by its ID.

obx app identity:organizations:preferences delete pre_stu901vwx234 --org-id org_abc123def456

Deleting all preferences

Removes every preference owned by the organization in a single operation.

obx app identity:organizations:preferences delete-all --org-id org_abc123def456

Contact Method Role