--- title: "API Flows" description: "Popular sequences of gRPC API requests for common Onli Platform workflows - from issuing assets to changing ownership and authentication patterns." author: "Onli Documentation Team" date: "2024-01-15" --- # 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 ```grpc 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 ```grpc 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 ```grpc 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 ```grpc 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 ```grpc 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 ```grpc 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 ```grpc 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: - [Buf.Build Integration](/api-reference/buf-build) for protocol definitions - [Postman Collection](/api-reference/postman) for interactive testing - [Requirements](/api-reference/requirements) for setup prerequisites For technical support with implementing these flows, contact our integration team.