The Owners object

The Owners object holds the users and groups that own a resource. It has two lists, users and groups, and each entry is a user or a group. Owners don’t have endpoints of their own. You read and set them on the resource they belong to.

The Owners object

{
  "users": [
    { "id": "3c4d5e6f-7081-9012-cdef-123456789012" }
  ],
  "groups": [
    { "id": "4d5e6f70-8192-0123-def1-234567890123" }
  ]
}

Resources with owners

Resource	Read with	Set with
Access Policy	Get and List, with `expand=owners`	Create and Patch

Attributes

Field	Type	Description
`users`	array	The users who own the resource. Each is `{id}`, or a full user when you expand `owners.users`. Always present.
`groups`	array	The groups that own the resource. Each is `{id}`, or a full group when you expand `owners.groups`. Always present.

Each id is the same ID that Get User or Get Group takes. Owners are users and groups directly, so a group’s members aren’t listed. Use List Group Members to read them.

Expanding fields with `expand`

A resource’s read endpoints leave owners out of the response unless you ask for it with expand. Without expand, the key is missing, not null.

`expand`	`owners` in the response
None	Left out
`owners`	Both lists, as `{id}` references
`owners.users`	`users` as full user objects, `groups` as `{id}` references
`owners.groups`	`groups` as full group objects, `users` as `{id}` references
`owners.users,owners.groups`	Both lists as full objects

Each path expands only its own list.
owners.users and owners.groups include owners, so you don’t need to send owners with them.
Expanding only adds fields. A {id} reference becomes the full object, and nothing is renamed or moved.
Expanded users are the same object that List Users returns, without custom_attributes. Expanded groups are the same object that List Groups returns.
Any other path under owners, such as owners.users.custom_attributes, returns 400.

On a list endpoint, expand applies to every item on the page. With expand=owners.users:

"owners": {
  "users": [
    {
      "id": "3c4d5e6f-7081-9012-cdef-123456789012",
      "email": "jane.smith@example.com",
      "given_name": "Jane",
      "family_name": "Smith",
      "status": "active"
    }
  ],
  "groups": [
    { "id": "4d5e6f70-8192-0123-def1-234567890123" }
  ]
}

With expand=owners.users,owners.groups:

"owners": {
  "users": [
    {
      "id": "3c4d5e6f-7081-9012-cdef-123456789012",
      "email": "jane.smith@example.com",
      "given_name": "Jane",
      "family_name": "Smith",
      "status": "active"
    }
  ],
  "groups": [
    {
      "id": "4d5e6f70-8192-0123-def1-234567890123",
      "app_id": "2b3c4d5e-6f70-8901-bcde-f12345678901",
      "integration_specific_id": "00g1a2b3c4d5e6f7g8h9",
      "name": "IT Admins",
      "description": "Okta admins.",
      "group_lifecycle": "synced",
      "source_app_id": "okta.com"
    }
  ]
}

Setting owners

Send owners with {id} references in both lists. The same shape works for users and groups:

{
  "owners": {
    "users": [
      { "id": "3c4d5e6f-7081-9012-cdef-123456789012" },
      { "id": "5e6f7081-9203-1234-ef12-345678901234" }
    ],
    "groups": []
  }
}

owners always replaces the full owner set:

You send	Result
`owners` with both lists	Both lists are replaced.
`owners` with only `users`	`users` is replaced, and `groups` is cleared. The same is true the other way round.
`owners` with two empty lists	Every owner is removed.
`"owners": null`	`400`. Leave `owners` out instead.
The same user or group twice	`400`
A field other than `id` on an owner	`400`
An `id` that isn’t a UUID	`400`
An ID that doesn’t match a user or group in your organization	`404`, without saying which ID. An ID from another organization returns the same `404`.

A write that sends owners returns the resource with owners as {id} references, so you can confirm the change without a second read. A write that leaves owners out returns the resource without it. Each resource decides what happens when you leave owners out, and which methods accept it. Its page, linked from Resources with owners, covers that.

Who can do what

Reading owners. Even an {id} reference shows which users and groups exist. So every owners path, including plain expand=owners, needs the same permissions as List Users and List Groups, on top of permission to read the resource. Of the built-in roles, Admin, Read Only Admin, App Admin, and AppStore Read Only Admin have both. A caller missing either permission gets 403 for the whole request. This differs from most expand fields, which a response leaves out when you can’t read them, as Requesting fields with expand describes. Setting owners. Changing owners needs its own permission, separate from editing the rest of the resource. Being an owner doesn’t give it. It comes from your role in the organization, such as Admin. A caller without it gets 403, before Lumos looks up any owner ID, so the response doesn’t reveal which IDs exist.

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Owners object

Resources with owners

Attributes

Expanding fields with `expand`

Setting owners

Who can do what

​Resources with owners

​Attributes

​Expanding fields with expand

​Setting owners

​Who can do what

Resources with owners

Attributes

Expanding fields with `expand`

Setting owners

Who can do what