---
title: "Owners"
---
# Owners API

The Owners API provides methods for managing Owner identities on the Onli_One network. Every Onli has an Owner - an Onli ID tightly coupled to a Gene and stored in an Owner's Vault. Possessing anOnli ID enables Authentication and Authorization across the Onli_One network.
> Owners API refers to the [Onli ID RPC Service](https://buf.build/onlicorp/onli-id) and has it's own url separate and distinct from Onli Cloud Services.
## Core Concepts

**Owners vs Users vs Appliances**

- **Owners**: Onli ID entities tightly coupled to a Gene, stored in an Owner's Vault. Owners have complete control over their Owner Object.
- **Users**: Created and controlled by Appliance developers. Users are provisioned by the Appliance developer.
- **Appliances**: Applications that connect Owner Objects to User Objects. Appliances have complete control over their User Objects.

**Owner Creation Process**

When developing an Appliance, you are connecting an Owner Object to a User Object:
- **New Owner**: If the User is not an existing Owner, they can be provisioned by the Appliance using the CreateOwner call
- **Existing Owner**: If the user already exists, their Owner object can be added to your Appliance stack

**Prerequisites**

To assemble an Onli ID rpc request, you need:
- **user_id**: "Master ID", provided upon Appliance registration completion
- **app_key**: "Appliance Key", provided upon Appliance Developer registration

Both credentials are available once your Appliance Developer registration is complete. Please sign up at [OnliCloud.com](https://onlicloud.com) to get your credentials.

Resources:
- [Onli ID API Buf.Build Protocol Buffers](https://buf.build/onli/api) - Complete protocol buffer definitions
- [Onli ID API Postman Collection](https://www.postman.com/onlicorp/onli/collection/6797a4d869c951396fe47855) - Interactive examples

## CreateOwner

CreateOwner creatse a new user object from a minted `onli_you_id` and triggers an email invitation to the potential Owner. 

To CreateOwner, you need an `onli_you_id`. The `onli_you_ids` are minted by Onli Administrators and provided to the Appliance Owner. Each `onli_you_id` can be used to create a new owner and add them as a member of your Appliance. You need to provide an Email and Phone number in the request. A confirmation Email and SMS will be sent which will be used by the potential Owner in the BuildYou phase.

**Resources:** [Proto](https://buf.build/onli/api/file/main:onli/id/v1/id.proto) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a1bfb80e5f117f0f6a798?ctx=documentation)

**Prerequisites:** `onli_you_id`, `app_symbol`. `user_class` & `user_behaviors` are customizable by Appliance Owners, through Appliance Tray APIs. Ensure your Appliance has `user_class` & `user_behaviors` configured in your Appliance Tray.

### `CreateRequest`

| Field | Description |
|-------|-------------|
| `data` | Container for identity and context information |
|         `identity` | Owner identity information |
|                 `onli_you_id` | Unique identifier for the user object and potential Owner |
|                 `email` | Owner's email address |
|                 `phone` | Owner's phone number (+X International Format) |
|         `context` | Application context information |
|                 `appliances` | Appliance-specific configurations |
|                         `\{app_symbol\}` | Your App Symbol |
|                                 `user_class` | User class, customizable classification by Appliance Owners, through Appliance Tray APIs (e.g., "owner") |

### `IdentityResponse`

| Field | Description |
|-------|-------------|
| `identity` | identity container |
|         `onli_you_id` | Unique identifier for the user object and potential Owner |

### Example Request

```json
{
    "data": {
        "identity": {
            "onli_you_id": "usr-48a757fa-a0fb-5204-b0ca-96c91d3acbc3", 
            "created_by_app": "ENGMA",
            "email": "my@email.com",
            "phone": "+0000000000111"
        },
        "context": {
            "appliances": {
                "ENGMA": {
                    "user_class": "owner"
                }
            }
        }
    }
}
```

### Example Response

```json
{
    "identity": {
        "onli_you_id": "usr-48a757fa-a0fb-5204-b0ca-96c91d3acbc3"
    }
}
```


### Email Invitation Example

When the CreateOwner request is successfully completed, the Owner receives an email invitation. It contains information for downloading the OnliYou app and completing the buildYou phase; The email also contains the invite code and app symbol necessary for Owner creation. 
> NOTE: the email invitation is sent by the Onli platform. It is not sent by your Appliance.

![Email Invitation Example](/email_invite_example_screenshot.png)

### Next Steps

After successfully creating an Owner:
1. The Owner will receive an email invitation
2. Owner can complete setup in the OnliYou app
3. The status of the Owner can be checked using the GetOwner, FetchOwner, or ListOwner methods
4. Once the Owner is created, you can use the OnliCloud APIs to issue assets and send gene related requests to the Owner


## GetOwner

Retrieve an Onli Owner Object and relevant User Appliance stored data.

Onli_One runs on the cloudMode storage framework. This means every object has three sections or set of values (called entities): Identity, Content and Context. The data stored in Identity is controlled by the Owner. Context contains Appliance controlled information. The key `context.appliances` is a dynamic key-value portion that appliance developers can use that is a part of the Owner Object. It is up to the appliance developers to create and maintain the data in this section. Storing context dependent data in `context.appliances` is an excellent way to extend the owners attributes for your Appliance.

**Resources:** [Proto](https://buf.build/onlicorp/onli-id/docs/main:userApi#userApi.OnliIdService.GetOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a1b270979325625acdca7?ctx=documentation)

**Prerequisites:** `app_symbol`, `onli_you_id` of the Owner you want to retrieve.

### `GetOwnerRequest`

| Field | Description |
|-------|-------------|
| `app_symbol` | Your App Symbol |
| `onli_you_id` | Unique identifier for the Owner you want to retrieve |

### `GetOwnerResponse`

| Field | Description |
|-------|-------------|
| `data` | Container for identity and context information |
|         `identity` | Owner identity information (controlled by Owner) |
|                 `onli_you_id` | Unique identifier for the Owner |
|                 `first_name` | Owner's first name |
|                 `alt_name` | Owner's alternative name |
|                 `last_name` | Owner's last name |
|                 `email` | Owner's primary email address |
|                 `alt_email` | Owner's alternative email address |
|                 `username` | Owner's username |
|                 `address` | Owner's primary address |
|                 `address_2` | Owner's secondary address line |
|                 `city` | Owner's city |
|                 `state` | Owner's state/province |
|                 `postal` | Owner's postal/zip code |
|                 `country` | Owner's country |
|                 `phone` | Owner's phone number (+X International Format) |
|                 `company` | Owner's company |
|                 `status` | Owner's status (e.g., "STATUS_ACTIVE") |
|         `context` | Application context information (controlled by Appliance) |
|                 `appliances` | Appliance-specific configurations |
|                         `\{app_symbol\}` | Your App Symbol configuration |
|                                 `user_class` | User class assigned to this Owner |
|                                 `status` | Owner's status within your Appliance (e.g., "STATUS_APP_ACTIVE") |
|                                 `extra` | JSON string containing custom key-value data for additional Appliance-specific information |

### Example Request

```json
{
    "app_symbol": "ENGMA",
    "onli_you_id": "usr-afa3dae3-e37e-525e-927d-f65660dd2d30"
}
```

### Example Response

```json
{
    "data": {
        "identity": {
            "onli_you_id": "usr-afa3dae3-e37e-525e-927d-f65660dd2d30",
            "first_name": "bob",
            "alt_name": "test-alt_name",
            "last_name": "tester",
            "email": "email@1234.com",
            "alt_email": "test-alt_email",
            "username": "ian-tester-10",
            "address": "test-address",
            "address_2": "test-address-2",
            "city": "test-city",
            "state": "test-state",
            "postal": "test-postal",
            "country": "test-country",
            "phone": "+0000000000124",
            "company": "test-company",
            "status": "STATUS_ACTIVE"
        },
        "context": {
            "appliances": {
                "ENGMA": {
                    "user_class": "onliu-tester",
                    "status": "STATUS_APP_ACTIVE"
                }
            }
        }
    }
}
```

### Next Steps

After successfully retrieving an Owner:
1. Use the identity data to display Owner information in your application
2. Use the context.appliances data to understand the Owner's relationship with your Appliance
3. Store or cache relevant information for your application's use
4. Use other Onli ID API methods to update or manage the Owner as needed


## FetchOwner

A lightweight Get-ish method that returns a singular owner attribute value instead of a scope of owner attributes or entire entity.

FetchOwner allows you to retrieve specific attributes from the Owner Object without fetching the complete data set. This is useful when you only need a particular piece of information like the username, email, or any custom attribute stored in the `context.appliances` section.

**Resources:** [Proto](https://buf.build/onlicorp/onli-id/docs/main:userApi#userApi.OnliIdService.FetchOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a1a020979325625acda51?ctx=documentation)

**Prerequisites:** `app_symbol`, `onli_you_id` of the Owner, and the specific `condition` (attribute path) you want to retrieve.

### `FetchOwnerRequest`

| Field | Description |
|-------|-------------|
| `app_symbol` | Your App Symbol |
| `onli_you_id` | Unique identifier for the Owner |
| `condition` | Attribute path to retrieve (e.g., "identity.username", "context.appliances.\{app_symbol\}.user_class") |

### `FetchOwnerResponse`

| Field | Description |
|-------|-------------|
| `data` | Container for the requested attribute |
|         `identity` | Identity section (if condition targets identity attributes) |
|                 `\{attribute\}` | The specific attribute value requested |
|         `context` | Context section (if condition targets context attributes) |
|                 `appliances` | Appliance-specific data (if condition targets appliance attributes) |
|                         `\{app_symbol\}` | Your App Symbol data |
|                                 `\{attribute\}` | The specific appliance attribute requested (including extra object) |

### Example Request

```json
{
    "app_symbol": "ENGMA",
    "onli_you_id": "usr-afa3dae3-e37e-525e-927d-f65660dd2d30",
    "condition": "identity.username"
}
```

### Example Response

```json
{
    "data": {
        "identity": {
            "username": "my-username"
        }
    }
}
```

### Common Condition Examples

| Condition | Returns |
|-----------|---------|
| `identity.username` | Owner's username only |
| `identity.email` | Owner's email address only |
| `identity.status` | Owner's entire user object status |
| `context.appliances.\{app_symbol\}.user_class` | User class for your appliance only |
| `context.appliances.\{app_symbol\}.status` | Owner's status within your appliance only; controlled by your Appliance |
| `context.appliances.\{app_symbol\}.extra` | JSON string containing custom key-value data for your appliance |

### Next Steps

After successfully fetching a specific Owner attribute:
1. Use the returned value directly in your application logic
2. Cache the specific attribute if needed for performance
3. Use FetchOwner for efficient attribute checking without full Owner data retrieval
4. Combine with other Onli ID API methods for complete Owner management


## ListOwner

List all of the Owners that are Users of your Appliance. Retrieve full data objects or specified attribute values in the conditions.

ListOwner allows you to get a comprehensive list of all Owners associated with your Appliance. You can retrieve complete Owner data objects or specify particular attributes using the condition parameter. This is useful for displaying user lists, generating reports, or performing bulk operations on your Appliance's user base.

**Resources:** [Proto](https://buf.build/onlicorp/onli-id/docs/main:userApi#userApi.OnliIdService.ListOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/6797b2b769c951396fe49312)

**Prerequisites:** `app_symbol` and optionally `condition` to specify what data to retrieve, plus `meta` parameters for pagination.

### `ListOwnerRequest`

| Field | Description |
|-------|-------------|
| `app_symbol` | Your App Symbol |
| `condition` | Data retrieval specification (e.g., "full" for complete objects, or specific attribute paths) |
| `meta` | Metadata for pagination and filtering |
|         `limit` | Maximum number of Owners to return in the response |

### `ListOwnerResponse`

| Field | Description |
|-------|-------------|
| `data` | Array of Owner objects matching the request criteria |
|         `[\{owner_object\}]` | Individual Owner data based on condition parameter |
|                 `identity` | Owner identity information (if condition includes identity data) |
|                         `onli_you_id` | Unique identifier for the Owner |
|                         `first_name` | Owner's first name |
|                         `last_name` | Owner's last name |
|                         `email` | Owner's email address |
|                         `phone` | Owner's phone number |
|                         `status` | Owner's status (e.g., "STATUS_ACTIVE", "STATUS_INVITED") |
|                         `...` | Other identity fields based on condition |
|                 `context` | Application context information |
|                         `appliances` | Appliance-specific configurations |
|                                 `\{app_symbol\}` | Your App Symbol configuration |
|                                         `user_class` | User class assigned to this Owner |
|                                         `status` | Owner's status within your Appliance |
|                                         `extra` | JSON string containing custom key-value data for additional Appliance-specific information |

### Example Request

```json
{
    "app_symbol": "ENGMA",
    "condition": "full",
    "meta": {
        "limit": 10
    }
}
```

### Example Response

```json
[
    {
        "identity": {
            "onli_you_id": "usr-c583f88e-a318-5c11-a84b-f4f4b4926ade",
            "email": "e@fail.com",
            "phone": "+0000000000317",
            "status": "STATUS_INVITED"
        },
        "context": {
            "appliances": {
                "ENGMA": {
                    "user_class": "owner",
                    "status": "STATUS_APP_ACTIVE"
                }
            }
        }
    },
    {
        "identity": {
            "onli_you_id": "usr-d7da6d6a-4ab1-53f4-a599-51f97840aa93",
            "first_name": "SOPHIA",
            "alt_name": "REBECCA",
            "last_name": "MEYERS",
            "email": "e@mail.com",
            "alt_email": "ian@onlicorp.com",
            "username": "scooter1025",
            "address": "124 Fake Road",
            "city": "Concord",
            "state": "MA",
            "postal": "01742",
            "country": "USA",
            "phone": "+0000000000217",
            "company": "Onlicorp",
            "status": "STATUS_ACTIVE"
        },
        "context": {
            "appliances": {
                "ENGMA": {
                    "user_class": "owner",
                    "status": "STATUS_APP_ACTIVE",
                    "extra": "{\"foo\": \"bar\", \"baz\": \"qux\"}"
                }
            }
        }
    }
]
```

### Common Condition Examples

| Condition | Returns |
|-----------|---------|
| `full` | Complete Owner objects with all available data |
| `identity.email` | Only email addresses for all Owners |
| `identity.status` | Only status information for all Owners |
| `context.appliances.\{app_symbol\}.user_class` | Only user class assignments for all Owners |
| `context.appliances.\{app_symbol\}.extra` | JSON strings containing custom key-value data for all Owners |

### Pagination & Filtering

Use the `meta` object to control the response:
- **`limit`**: Maximum number of Owners to return
- **Pagination**: Use multiple requests with different limits/offsets as needed

### Next Steps

After successfully listing Owners:
1. Process the returned Owner array for your application's needs
2. Use individual `onli_you_id` values with GetOwner or FetchOwner for detailed operations
3. Filter and sort the results based on status, user_class, or other attributes
4. Implement pagination for large Owner lists to improve performance


## UpdateOwner

Update an attribute of an Owner's Appliance data by specifying the attribute and desired value to update.

UpdateOwner gives developers control over the appliances attribute in the RPC message. While this RPC does not replace the entire existing block (re: REST PUT), please take care not to update the entire context of an Owner when only one attribute is desired. UpdateOwner attributes will only be updated if the attribute exists, thus if the attribute doesn't exist, the service will create the key value for the specified owner.

**Resources:** [Proto](https://buf.build/onlicorp/onli-id/docs/main:userApi#userApi.OnliIdService.UpdateOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a1af9de5f880cbcd6e572)

**Prerequisites:** `onli_you_id` of the Owner to update and the specific appliance context attributes you want to modify.

### `UpdateOwnerRequest`

| Field | Description |
|-------|-------------|
| `data` | Container for identity and context information |
|         `identity` | Owner identity information (for identification) |
|                 `onli_you_id` | Unique identifier for the Owner to update |
|         `context` | Application context information to update |
|                 `appliances` | Appliance-specific configurations to modify |
|                         `\{app_symbol\}` | Your App Symbol configuration |
|                                 `user_class` | User class to update (optional) |
|                                 `status` | Status to update (optional) |
|                                 `extra` | JSON string containing custom key-value data to update (optional) |

### `UpdateOwnerResponse`

| Field | Description |
|-------|-------------|
| `identity` | Confirmation of the updated Owner |
|         `onli_you_id` | Unique identifier of the updated Owner |

### Example Request

```json
{
    "data": {
        "identity": {
            "onli_you_id": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450"
        },
        "context": {
            "appliances": {
                "ENGMA": {
                    "extra": "{\"foo\":\"bar\"}"
                }
            }
        }
    }
}
```

### Example Response

```json
{
    "identity": {
        "onli_you_id": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450"
    }
}
```

### Update Behavior

| Scenario | Behavior |
|----------|----------|
| **Attribute exists** | Updates the existing attribute value |
| **Attribute doesn't exist** | Creates the new key-value pair |
| **Partial updates** | Only specified attributes are modified; others remain unchanged |
| **Identity data** | Cannot be updated via this method (identity is Owner-controlled) |

### Common Update Examples

| Update Target | Request Structure |
|---------------|-------------------|
| **User Class** | `context.appliances.\{app_symbol\}.user_class: "new_class"` |
| **Status** | `context.appliances.\{app_symbol\}.status: "STATUS_INACTIVE"` |
| **Extra** | `context.appliances.\{app_symbol\}.extra: "\{\"old_key\":\"new_value\"\}"` |

### Best Practices

- **Targeted Updates**: Only include the specific attributes you want to change
- **Preserve Existing Data**: Remember that unspecified attributes remain unchanged
- **Extra Field Format**: Ensure `extra` field contains properly escaped JSON string

### Next Steps

After successfully updating an Owner:
1. Use GetOwner or FetchOwner to verify the update was applied correctly
2. Update your application's local cache if applicable
3. Log the change for audit purposes if required
4. Handle any dependent business logic that relies on the updated attributes


## AskToAddOwner

Add an existing Owner as a User of your Appliance. Serves as a notification that requires Owner authorization to complete.

AskToAddOwner serves as a confirmation of an existing Owner requesting to be a member of your Appliance. Owners must first request to be a member of your Appliance, then and only then will you be able to add them as an Owner of your Appliance. All Appliances can receive membership requests through the Onli Cloud App.

### Owner Membership Scenarios

| Scenario | Initiator | Process | Next Step |
|----------|-----------|---------|-----------|
| **New Owner Creation** | App developer | Invite a brand new user to become an owner and member of your appliance | Use **CreateOwner** - triggers invite email to potential member |
| **Non-existing Owner Request** | Non-existing user | Uses Onli You app to request invitation with app symbol | App dev notified via GetQueueMsg → Use **CreateOwner** to accept request |
| **Existing Owner Request** | Existing owner | Member of other appliances requests invitation to your appliance | App dev notified via GetQueueMsg → Use **AskToAddOwner** to offer membership |
| **App Dev Invitation** | App developer | App dev has valid email of existing owner and offers membership | Use **AskToAddOwner** → Owner receives notification to accept/deny |

### Notification & Queue System

- **App Developer Notifications**: Received through Appliance Tray Services message queue
- **Queue Message Retrieval**: Use `GetQueueMsg` to check for membership requests
- **Owner Notifications**: Sent through Onli You app for acceptance/denial
- **Request Tracking**: Each scenario generates trackable request IDs

**Resources:** [Proto](https://buf.build/onlicorp/onli-id/docs/main:userApi#userApi.OnliIdService.AskToAddOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a1e17412d99eb59ebcdd5)

**Prerequisites:** `onli_you_id` of an existing Owner who has requested to join your Appliance, and `app_symbol` of your Appliance.

### `AskToAddOwnerRequest`

| Field | Description |
|-------|-------------|
| `data` | Container for the add owner request information |
|         `onli_you_id` | Unique identifier of the existing Owner to add |
|         `app_symbol` | Your App Symbol (invite owner from a different appliance) |
|         `appliance` | Appliance configuration for the new Owner |
|                 `user_class` | User classification to assign to the Owner (e.g., "owner") |

### `AskToAddOwnerResponse`

| Field | Description |
|-------|-------------|
| `onli_you_id` | Unique identifier of the Owner being added |
| `ask_to_add_owner_id` | Unique identifier for this add owner request |
| `app_symbol` | Your App Symbol confirming the request |

### Example Request

```json
{
    "data": {
        "onli_you_id": "usr-afa3dae3-e37e-525e-927d-f65660dd2d30",
        "app_symbol": "ENGMA",
        "appliance": {
            "user_class": "owner"
        }
    }
}
```

### Example Response

```json
{
    "onli_you_id": "usr-afa3dae3-e37e-525e-927d-f65660dd2d30",
    "ask_to_add_owner_id": "61c81618-1455-41c6-b5b9-6a1d04be5612",
    "app_symbol": "ENGMA"
}
```