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 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 to get your credentials.

Resources:

• Onli ID API Buf.Build Protocol Buffers - Complete protocol buffer definitions
• Onli ID API Postman Collection - 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 + Example

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

IdentityResponse

Example Request

{
    "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

{
    "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.

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 + Example

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

GetOwnerRequest

GetOwnerResponse

Example Request

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

Example Response

{
    "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",
            [object Object][object Object] [object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

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 + Example

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

FetchOwnerRequest

FetchOwnerResponse

Example Request

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

Example Response

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

Common Condition Examples

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 + Example

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

ListOwnerRequest

ListOwnerResponse

Example Request

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

Example Response

[
    {
        "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"
                }
            }
        }
    },
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

Common Condition Examples

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 + Example

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

UpdateOwnerRequest

UpdateOwnerResponse

Example Request

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

Example Response

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

Update Behavior

Common Update Examples

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

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 + Example

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

AskToAddOwnerRequest

AskToAddOwnerResponse

Example Request

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

Example Response

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