Onli Cloud API

The Onli Cloud API provides the compute, storage, networking, database, and platform services you need to interact with Owners on the Onli_One Network. Onli Cloud Services is a functions-as-a-service platform that, upon an authenticated request, creates Owners (Onli_ID), asks owners to move assets (AskToMove), hosts the master Oracle, and hosts Treasury Vault where Assets are held for issuance to Owners (Issue).

Onli Cloud API refers to the Onli Cloud RPC Service and has it's own url separate and distinct from Onli ID Owner Services.

Treasury is an Onli-Cloud service that stores, defines and issues genomes. The Treasury Vault manages asset issuance and distribution of genomes across the Onli_One network.

• Onli Cloud API Buf.Build Protocol Buffers - Complete protocol buffer definitions
• Onli Cloud API Postman Collection - Interactive examples

Issue

Issue appliance assets from the Treasury Vault to any member of your Appliance. Issuance incurs a one-time issuance fee of $0.05 USD per asset. The issuance fee is billed to the admin developer account.

Issue genomes from the treasury to an owner. You can issue using either amount as input or onli_ids. When onli_ids are provided, the amount parameter is ignored.

Resources: Proto + Example

IssueInput

IssueResponse

Example Request

{
    "to": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "app_symbol": "ENGMA",
    "amount": "3000",
    "which_device": "desktop"
}

Example Response

{
    "issue_id": "d8042a84-5663-4cb2-94f7-aa61b581f320",
    "issued_at": "1741701330",
    "owner_changed_at": "1741701331",
    "delivered_at": "1741701331",
    "pkg_tag": "f608bcd5-4acb-49db-b288-54ea66800af0"
}

Issuance Options

Genus determines how amount is interpreted

Issuance Fee: $0.05 USD per genome asset issued

AskToMove

Only an Owner can move an issued Asset. AskToMove is an authenticated request from an Appliance to an asset Owner to move a specified amount of Assets from an Onli_You vault to an appliance settlement locker for the purposes of settlement.

AskToMove workflow is a bi-directional stream used to ask an owner to move their genomes to their locker which can then be used with ChangeOwner to transfer to another owner's locker. This request is initiated by a master and a notification is sent to the owner. The owner can either accept or deny the request; only accepted requests will pack genomes and move them to the settlement locker. Assets that remain in a settlement locker and have not changed ownership in a discrete time window will automatically be returned to the original owner's cloud vault.

Resources: Proto + Example

AskToMoveReq

AskToMoveRecord

Example Request

{
    "add_settle_time": "0",
    "amount": "1",
    "app_symbol": "ENGMA",
    "note": {
        "behavior": "move",
        "body": "Accept ask to move request from ENGMA"
    },
    "to": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450"
}

Example Response

{
    "ask_to_move_id": "61c81618-1455-41c6-b5b9-6a1d04be5612",
    "pkg_tag": "f608bcd5-4acb-49db-b288-54ea66800af0",
    "to": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "note": {
        "behavior": "move",
        "body": "Accept ask to move request from ENGMA"
    },
    "amount": "1",
    "app_symbol": "ENGMA",
    "asset_balance": "2008",
    "notified_at": "1741866953",
    "status": "OPEN",
    "expires_at": "1757634953"[object Object]
[object Object][object Object][object Object][object Object]

Stream Workflow

Request Status Values

Settlement Locker Behavior

• Purpose: Temporary holding area for assets during change of ownership
• Access: Only accessible for ChangeOwner operations
• Visibility: Owners can view, but not alter or change, the contents of their settlement locker
• Timeout: Assets automatically return to Owner if not used within time window

Next Steps

After successfully initiating an AskToMove request:

1. Monitor the ask_to_move_id for status updates; use GetAskToMoveRecord to retrieve the status
2. Use the ask_to_move_id with ChangeOwner to complete the transfer

ChangeOwner

ChangeOwner is an authenticated request to change the Owner of Onli. ChangeOwner results in Genome Editing.

Only Assets in a settlement locker can be accessed by the Transfer Agent. This results in genome editing. Genome editing can only be executed by the Transfer Agent inside the trusted execution environment of Onli_One. The request to change an owner while it is a request from an Appliance, this request must be authorized by an Owner. To obtain this authorization, an AskToMove is a prerequisite.

Resources: Proto + Example

Prerequisites: Valid ask_to_move_id from a completed AskToMove request with status "OPEN", sender and recipient user IDs, and target device type.

ChangeOwnerInput

ChangeOwnerResponse

Example Request

{
    "from": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "to": "usr-d7da6d6a-4ab1-53f4-a599-51f97840aa93",
    "ask_to_move_id": "61c81618-1455-41c6-b5b9-6a1d04be5612",
    "app_symbol": "ENGMA",
    "amount": 1,
    "which_device": "desktop"
}

Example Response

{
    "ask_to_move_id": "61c81618-1455-41c6-b5b9-6a1d04be5612",
    "evolve_id": "5487fa89-b0ca-47ec-a582-79a5ee61d808",
    "received_at": "1742211777",
    "owner_evolved_at": "1742211777",
    "delivered_at": "1742211778"
}

Process Flow

1. Prerequisite Check: Validates AskToMove request has "OPEN" status
2. Asset Access:Logistics Ageng moves assets from settlement locker to Transfer Agent
3. Genome Editing: Secure evolution of genome ownership records
4. Ownership Transfer: Updates Oracle with new ownership oracle helices
5. Asset Delivery: Delivers assets to recipient's specified device vault or locker if recipient owner does not have an active vault
6. Completion: Updates AskToMove status to "CLOSED"

Idempotency & Retry Semantics

ChangeOwner uses server-driven deduplication anchored on ask_to_move_id. There is no client-supplied idempotency key, header, or replay token — the AskToMove record's status is the dedup mechanism.

Contract:

• Every AskToMove generates a unique, server-issued ask_to_move_id. IDs are never reused.

• A successful ChangeOwner transitions the corresponding AskToMove record from OPEN to CLOSED.

• A second ChangeOwner with the same ask_to_move_id fails the prerequisite check and returns:

  Copy code

  Code: Unauthenticated
  Err:  askToMoveRecord.Status is not open
  

• The original ChangeOwnerResponse (evolve_id, received_at, owner_evolved_at, delivered_at) is not replayed on the second call. The evolve_id is also not recoverable from AuthLog — AuthLog only captures the AskToMove event and the Owner's approval, not the ChangeOwner response. Clients must persist the response from the first successful call.

• The same Unauthenticated error covers any non-OPEN status, not just CLOSED. Inspect AskToMoveRecord.status to distinguish "already done" (CLOSED) from "no longer actionable" (DENIED, ASKED_EXPIRED, OPEN_EXPIRED, RETURNED, HOLD, FAILED).

Retry guidance:

For the full error catalog, see the proto definition. The table below summarises which classes are safe to retry.

AskToMove side: AskToMove is not idempotent on the request side. Each call generates a new ask_to_move_id and sends a fresh notification to the Owner. To check the state of an existing request without renotifying, use GetAskToMoveRecord rather than re-issuing the AskToMove.

AuthenticateOwner

AuthenticateOwner is an Onli_ID RPC that authenticates owners on the Onli_One network using our patented authentication system. Since Owners control their Owner_Object, their express permission must be requested to use their credentials. Authentication is an Onli_ID transaction that results in the editing of Genes.

The method operates as a bi-directional stream request from a master to an owner, staying open for a 60-second interval before expiring. When initiated, the owner receives a notification in their OnliYou app and can accept or deny the request. Accepting the request authenticates the owner and returns their cloud vault asset balance to the master. For more detailed asset information, masters can use the AskAssetBalance method with the owner's authorization.

AuthenticateOwner supports 3 different methods of authentication:

• basic: Uses the owner's gene to authenticate
• reverse-mfa: Uses the owner's gene to authenticate alongside a master generated string for the owner to input during acceptance
• reverse-hash: Uses the owner gene to authenticate alongside a master generated nonce for the gene to sample during acceptance (Note: reverse hash will be available in a future update)

The server will select authentication method based on the input request. Onli Cloud marks the authenticate_owner_record as ASKED at init. If the owner accepts then it will be marked as ACCEPTED. Else if the owner denies then it will be marked as DENIED. Else if the owner doesn't respond within the 60-second interval then it will be marked as EXPIRED.

Resources: Proto + Example

Prerequisites: Target Owner user_id, app_symbol, authentication message body, and optionally a rev_string for reverse-mfa authentication. The onus is on the master to share the rev_string with the owner, if this authentication method is used.

AuthenticateOwnerReq

AuthenticateOwnerRecord

Authentication Methods

Example Request (Basic Authentication)

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "app_symbol": "ENGMA",
    "body": "Please Confirm Request to Authenticate from ENGMA"
}

Example Response (Basic Authentication)

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "auth_log_id": "auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0",
    "authentication_status": "AuthenticationStatusACCEPTED",
    "auth_type": "BASIC",
    "rev_string": "",
    "app_symbol": "ENGMA",
    "body": "Please Confirm Request to Authenticate from ENGMA",
    "asset_balance": "8165210"
}

Example Request (Reverse-MFA Authentication)

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "app_symbol": "ENGMA",
    "body": "Please Confirm Request to Authenticate from ENGMA",
    "rev_string": "96"
}

Example Response (Reverse-MFA Authentication)

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "auth_log_id": "auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0",
    "authentication_status": "AuthenticationStatusACCEPTED",
    "auth_type": "REVERSE_MFA",
    "rev_string": "96",
    "app_symbol": "ENGMA",
    "body": "Please Confirm Request to Authenticate from ENGMA",
    "asset_balance": "51"
}

Authentication Status Values

Stream Behavior

• Bi-directional: Real-time communication between Appliance and Owner
• Time-limited: Stream expires after 60-second interval
• Auto-close: Stream automatically closes after Owner response or timeout
• Real-time: Owner receives immediate notification in Onli You app

Next Steps

After successfully authenticating an Owner:

1. Use the auth_log_id to track the authentication event
2. Store the authentication status for your application's security logic
3. Proceed with authenticated operations using the confirmed Owner identity
4. Use AuthLog method to retrieve detailed authentication records if needed
5. Implement timeout handling for EXPIRED authentication attempts

AuthorizeBehavior

AuthorizeBehavior is a bi-directional stream that masters use to confirm explicit behaviors from owners. Much like AuthenticateOwner, the owner will receive a notification in their OnliYou app to authorize a behavior by either accepting or denying the request. It is a feature of a capability-based authorization system; owners must explicitly authorize behaviors before they can be executed, and only behaviors granted to them by the appliance owner can be executed. The behaviors are a master created array of strings that can be configured with the appliance tray APIs. Move is the first available behavior by default on every appliance.

Resources: Proto + Example

Prerequisites: Target Owner user_id, app_symbol, specific behavior to authorize, and message body explaining the authorization request.

AuthorizeBehaviorReq

AuthorizeBehaviorRecord

Example Request

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "app_symbol": "ENGMA",
    "note": {
        "behavior": "login",
        "body": "Please Confirm Request to Authorize from ENGMA"
    }
}

Example Response

{
    "owner": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
    "auth_log_id": "auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0",
    "authentication_status": "AuthenticationStatusACCEPTED",
    "app_symbol": "ENGMA",
    "note": {
        "behavior": "login",
        "body": "Please Confirm Request to Authorize from ENGMA"
    }
}

Default Behaviors

Behavior Configuration

• Appliance Tray APIs: Use to configure custom user_behaviors and user_classes for your appliance
• User Type Requirement: Behavior must exist under the user class in Onli ID, and the owner must be of that user class (set in the Owner Object, see UpdateOwner and CreateOwner)
• Master Control: App developers create and manage behavior arrays alongside user_classes

Authorization Status Values

Next Steps

After successfully authorizing a behavior:

1. Use the auth_log_id to track the authorization event
2. Store the authorization status for your application's permission logic
3. Execute the authorized behavior with confirmed Owner permission
4. Use AuthLog method to retrieve detailed authorization records if needed
5. Configure additional behaviors via Appliance Tray APIs as needed

AuthLog

Owners possess an immutable chain of all transactions with their Gene stored in the Onli_ID AuthLog. This log is an accounting method to gather request and response data from a specific appliance-owner Onli_ID event. Masters have access to auth log events that they've triggered through this API method; Owners possess their own auth log inside of their Onli You app.

Utilize accounting by retrieving a specific auth log entry to review the complete request and response data for any authentication or authorization event.

Resources: Proto + Example

Prerequisites: app_symbol and auth_log_id from a previous authentication or authorization event.

AuthLogRequest

AuthLogResponse

Example Request

{
    "app_symbol": "ENGMA",
    "auth_log_id": "auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0"
}

Example Response

{
    "AuthLogId": "auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0",
    "TS": "1738763781676826463",
    "WhichSecurityMethod": "ask_to_move_stream",
    "WhichAppliance": "ENGMA",
    "GeoData": null,
    "Request": "{ \"to\": \"usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450\", \"note\": { \"behavior\": \"move\", \"body\": \"Accept ask to move request from ENGMA\" }, \"app_symbol\": \"ENGMA\", \"amount\": 1 }",
    "Response": "{ \"ask_to_move_id\": \"61c81618-1455-41c6-b5b9-6a1d04be5612\", \"pkg_tag\": \"e484868e-89db-406e-882f-321e9341977c\", \"to\": \"usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450\", \"note\": { \"behavior\": \"move\", \"body\": \"Accept ask to move request from ENGMA\" }, \"amount\": 1, \"app_symbol\": \"ENGMA\", \"asset_balance\": 8, \"notified_at\": 1738763619, \"status\": 3, \"expires_at\": 1754531619, \"behavior_status\": true, \"authorization_status\": true, \"auth_log_id\": \"auth-log-19a0d6a8-f8b3-4f7d-9676-d6651d8db8c0\" }",
    "Err": ""
}

Security Methods Logged

Immutable Chain Properties

• Immutable: Auth log entries cannot be modified or deleted
• Complete Record: Contains full request and response JSON data
• Timestamp Precision: Nanosecond-level timestamp accuracy
• Access Control: Masters can only access logs they triggered
• Owner Access: Owners have complete access via OnliYou app

Data Format

• Request/Response Fields: Stored as JSON strings for complete data preservation
• Timestamp Format: Unix nanoseconds for precise event timing
• Error Tracking: Empty string indicates successful operation
• Geographic Data: May include location information (optional)

Use Cases

Next Steps

After successfully retrieving an auth log:

1. Parse the Request and Response JSON strings for detailed analysis
2. Use the timestamp for chronological event tracking
3. Check the Err field for any error conditions that occurred
4. Store relevant information for your application's audit requirements
5. Use the security method information to categorize different event types

Oracle

The Oracle is a database registry that keeps a record of the state of each genome across the system. The Oracle serves as evidence of the source of truth for the state of genomes across the network and maintains the record of ownership for each asset class you hold.

Access Control & Visibility

The Oracle operates under different access policies depending on the deployment environment:

Developer Instances

• The revealGenomes RPC is available to developers only
• Oracle data is private by default and viewable to developers for learning and understanding how Onli works
• Intended for development, testing, and educational purposes

Production Instances

• The Oracle is only viewable between Owners
• Oracle registry views are triggered by and authorized by the genome owners with a use policy (who, when, how long)
• Access requires explicit owner authorization and follows strict permission controls

Custom Production Instances

• Can be configured to use the Oracle at the developer's discretion
• This is not the normal configuration and requires specific setup
• Provides flexibility for specialized deployment scenarios

RevealGenomes

Returns oracle helix records for a specified owner. This method provides detailed genome state information including ownership history, asset details, and current status.

Resources: Proto

RevealGenomesInput

RevealGenomesResponse

Oracle Helix Record Fields

Example Request

{
    "search_condition": "what_face",
    "search_keyword": "^one|kilo$",
    "limit": "1000",
    "offset": "0",
    "sort_by": "what_face",
    "sort_order": "ASC",
    "who": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450"
}

Example Response

{
    "OracleHelices": [
        {
            "which_onli": "onl-d8042a84-5663-4cb2-94f7-aa61b581f320",
            "what_kind": "ABCDE",
            "what_type": "denomination",
            "what_face": "one",
            "last_owner_id": "usr-treasury-vault-system",
            "last_owner_name": "treasury",
            "current_owner_id": "usr-319d53bc-cf9b-5cea-9ec7-e6863a35b450",
            "current_owner_name": "example name",
            "blacklisted": false,
            "last_updated": "1738780042109969295"
        }
[object Object][object Object]

Search Capabilities

Error Handling

Oracle Functionality

The Oracle provides comprehensive genome tracking capabilities:

• Ownership History: Complete chain of ownership for each genome
• Asset Classification: Detailed categorization of genome types and values
• State Verification: Real-time status and blacklist information
• Search & Discovery: Flexible querying with regex and wildcard support
• Audit Trail: Immutable record of all genome state changes

Use Cases

Next Steps

After successfully querying the Oracle:

1. Parse the OracleHelices array for detailed genome information
2. Use the ownership data for verification and compliance purposes
3. Monitor last_updated timestamps for change detection
4. Check blacklisted status before processing assets
5. Use search capabilities to filter and analyze specific asset classes

Additional Methods

The Onli Cloud API includes several other methods for comprehensive asset and genome management:

• DefineGenomeStream: Create and configure genome definitions
• Blacklist: Mark genomes as blacklisted for security
• List: Retrieve lists of genomes and assets
• UpdateSettlementTime: Modify settlement timing parameters
• GetAskToMoveRecord: Retrieve transfer request details
• ReturnAskToMove: Cancel or return transfer requests
• AskToAdd: Request to add assets or permissions
• AskAssetBalance: Query asset balance information
• DrawerBalance: Check drawer balance information
• GetLogisticsInfo: Retrieve logistics and shipping details
• GetPkgSlip: Access package slip information

Detailed documentation for each method is available in their respective sections.