API Flows

This section documents the most commonly used sequences of gRPC API requests for typical Onli Platform workflows. These flows represent real-world usage patterns that help you understand how the various API calls work together to accomplish common tasks.

Overview

The Onli Platform API flows are organized into three main levels of complexity:

  • Level 1: Basic asset issuance to your first owner
  • Level 2: Asset ownership transfer between owners
  • Level 3: Authentication and authorization patterns

Each flow builds upon the previous level, creating a comprehensive understanding of how to work with the Onli Platform APIs in practice.

Level 1: Issue to Your First Owner

This flow covers the complete process of creating an owner and issuing your first asset to them. This is typically the starting point for any Onli Platform integration.

Prerequisites

  • Onli Cloud instance configured
  • Valid API credentials
  • iOS device for testing (OnliYou app)

Step-by-Step Flow

1. Create Owner

CreateOwner RPC

Purpose: Create a new owner account in the system
Required: Owner credentials and basic profile information

2. OnliYou App Setup

  • Download OnliYou app from App Store
  • Turn on developer mode in iOS settings
  • Add deployment_subdomain and credentials to verify user
  • Initialize vault in iOS app

3. Verify User Status

  • Check status of user in Onli Cloud web app
  • Ensure user status shows as "active"
  • Verify vault initialization completed successfully

4. Issue Asset

Issue RPC

Purpose: Create and deliver the first asset to the owner
Parameters: Asset definition, owner ID, initial metadata

5. Verification Steps

  • View package received in iOS app (OnliYou)
  • Check Oracle to verify ownership of newly issued assets (web app)
  • Direct owner to Auth Log in iOS app to show event (no entry yet at this stage)

Expected Outcomes

  • Owner successfully created and active
  • OnliYou app configured and vault initialized
  • Asset successfully issued and received
  • Oracle confirms ownership record
  • Event logged in OnliYou app

Level 2: Change Ownership of Assets to Second Owner

This flow demonstrates how to transfer asset ownership between two owners, including the request/response pattern that ensures secure transfers.

Prerequisites

  • Completed Level 1 flow (first owner with assets)
  • Second owner account ready to be created

Step-by-Step Flow

1. Create Second Owner

CreateOwner RPC

Requirement/Dependency: Must have a second owner before transfer can occur
Note: This owner will be the recipient of the asset transfer

2. Initiate Transfer Request

AskToMoveStream RPC

Purpose: Request permission from current owner to transfer asset
Target: Send request to the first owner (current asset holder)
Parameters: Asset ID, source owner, destination owner

3. Owner Accepts Transfer

  • First owner receives AskToMove request notification in OnliYou app
  • Owner reviews transfer details and accepts the request
  • System generates asktomoveid for the approved transfer

4. Monitor Transfer Status

  • Onli Cloud UX shows request status progression:
    • a) Request sent
    • b) Request accepted
    • c) asktomoveid stored for subsequent RPC request

5. Execute Ownership Change

ChangeOwner RPC

Purpose: Execute the actual ownership transfer
Required Parameter: asktomoveid from step 4
Process: System updates ownership records and transfers asset

6. Verification Steps

  • Check Oracle to verify ownership of assets moved
  • Confirm new owner appears in ownership records
  • Verify old owner no longer has asset access
  • Direct both owners to Auth Log in iOS app to show transfer events

Expected Outcomes

  • Second owner successfully created
  • Transfer request sent and accepted
  • Asset ownership successfully changed
  • Oracle reflects new ownership
  • Transfer events logged for both owners

Level 3: Authentication & Authorization

This advanced flow covers the authentication and authorization patterns that enable secure interactions between appliances and owners.

Authentication Flow

Owner Authentication

This sub-flow demonstrates how to authenticate an existing owner for secure operations.

1. Initiate Authentication

AuthenticateOwner RPC (stream, 60-second limit)

Purpose: Verify owner identity for secure operations
Target: Existing user with active vault
Time Limit: 60-second stream timeout for security

2. Owner Response Handling

  • Owner receives authentication notification in OnliYou app
  • Owner can accept or deny the authentication request
  • System maintains secure session during decision period

3. Complete Authentication

  • Onli Cloud web app displays authentication response
  • Stream ends automatically after response or timeout
  • Authentication result logged for audit purposes

4. Verification

  • Direct owner to Auth Log in iOS app to show authentication event
  • Verify authentication event recorded with timestamp and result

Authorization Flow

Behavior Authorization

This sub-flow shows how to authorize specific behaviors or actions for an authenticated owner.

1. Setup User Class and Behavior

  • Use appliance tray to create user class definition
  • Define specific user behavior example
  • Configure permission parameters and constraints

2. Initiate Authorization

AuthorizeBehavior RPC (stream)

Purpose: Request permission for specific behavior/action
Target: Authenticated owner
Parameters: Behavior definition, permission scope, duration

3. Owner Authorization Response

  • Owner receives behavior authorization notification in OnliYou app
  • Owner reviews requested permissions and behavior details
  • Owner can accept or deny the authorization request

4. Complete Authorization

  • Onli Cloud web app displays authorization response
  • Stream ends after owner response
  • Authorization permissions activated if approved

5. Verification

  • Direct owner to Auth Log in iOS app to show authorization event
  • Verify behavior permissions are properly configured
  • Test authorized behavior to ensure it works as expected

Expected Outcomes

  • Owner successfully authenticated
  • User class and behavior properly defined
  • Authorization request sent and processed
  • Permissions activated for approved behaviors
  • All auth events logged and auditable

Next Steps

After mastering these flows, explore:

For technical support with implementing these flows, contact our integration team.