> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Owners object

> The users and groups that own a resource, how to read them with expand, and the rules for setting them.

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](https://docs.lumos.com/reference/v1/objects/user.md) or a
[group](https://docs.lumos.com/reference/v1/objects/group.md). Owners don't have endpoints of their own. You read and set
them on the resource they belong to.

```json The Owners object theme={null}
{
  "users": [
    { "id": "3c4d5e6f-7081-9012-cdef-123456789012" }
  ],
  "groups": [
    { "id": "4d5e6f70-8192-0123-def1-234567890123" }
  ]
}
```

## Resources with owners

| Resource | Read with | Set with |
| - | - | - |
| [Access Policy](https://docs.lumos.com/reference/v1/objects/access-policy.md#setting-owners) | [Get](https://docs.lumos.com/api-reference/v1/access-policies/get-access-policy.md) and [List](https://docs.lumos.com/api-reference/v1/access-policies/list-access-policies.md), with `expand=owners` | [Create](https://docs.lumos.com/api-reference/v1/access-policies/create-access-policy.md) and [Patch](https://docs.lumos.com/api-reference/v1/access-policies/patch-access-policy.md) |

## Attributes

| Field | Type | Description |
| - | - | - |
| `users` | array | The users who own the resource. Each is `{id}`, or a full [user](https://docs.lumos.com/reference/v1/objects/user.md) when you expand `owners.users`. Always present. |
| `groups` | array | The groups that own the resource. Each is `{id}`, or a full [group](https://docs.lumos.com/reference/v1/objects/group.md) when you expand `owners.groups`. Always present. |

Each `id` is the same ID that [Get User](https://docs.lumos.com/api-reference/v1/users/get-user.md) or
[Get Group](https://docs.lumos.com/api-reference/v1/groups/get-group.md) takes. Owners are users and groups directly, so a
group's members aren't listed. Use [List Group Members](https://docs.lumos.com/api-reference/v1/groups/list-group-members.md)
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](https://docs.lumos.com/reference/v1/objects/user.md), `groups` as `{id}` references |
| `owners.groups` | `groups` as full [group objects](https://docs.lumos.com/reference/v1/objects/group.md), `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](https://docs.lumos.com/api-reference/v1/users/list-users.md) returns,
  without `custom_attributes`. Expanded groups are the same object that
  [List Groups](https://docs.lumos.com/api-reference/v1/groups/list-groups.md) 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`:

```json theme={null}
"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`:

```json theme={null}
"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:

```json theme={null}
{
  "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](#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](https://docs.lumos.com/api-reference/v1/users/list-users.md) and
[List Groups](https://docs.lumos.com/api-reference/v1/groups/list-groups.md), on top of permission to read the resource. Of
the [built-in roles](https://docs.lumos.com/reference/v1/objects/user.md#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`](https://docs.lumos.com/reference/v1/overview#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.