---
title: "Onli Cloud API"
---

# 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](https://buf.build/onlicorp/onli-cloud) 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](https://buf.build/onlicorp/onli-cloud) - Complete protocol buffer definitions
- [Onli Cloud API Postman Collection](https://www.postman.com/onlicorp/onli/collection/6797acdc69c951396fe48843) - 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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.Issue) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/6797b08509772940939b7c64)

### `IssueInput`

| Field | Description |
|-------|-------------|
| `to` | Recipient user ID for the asset issuance |
| `app_symbol` | Your App Symbol |
| `amount` | Total face value to issue - ignored if onli_ids provided |
| `which_device` | Destination vault type: "cloud" or "mobile" |
| `onli_ids` | Array of specific genome IDs to issue (optional, overrides amount) |

### `IssueResponse`

| Field | Description |
|-------|-------------|
| `issue_id` | Unique identifier for this issuance transaction |
| `issued_at` | Unix timestamp when the issue was processed |
| `owner_changed_at` | Unix timestamp when ownership was transferred |
| `delivered_at` | Unix timestamp when assets were delivered to recipient |
| `pkg_tag` | Package identifier for tracking the delivered assets |

### Example Request

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

### Example Response

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

| Method | Description | Use Case |
|--------|-------------|----------|
| **Amount-Based** | Specify total face value to issue | When you need a specific face value total |
| **ID-Based** | Specify exact genome IDs (individual files) | When you need specific genomes by ID |

### Genus determines how `amount` is interpreted

| Genus | Face Value | Amount Relationship | Example |
|-------|------------|-------------------|---------|
| **Symmetric** | `one` | Amount = genome count | `"amount": "21"` = 21 genome files (each face value 1) |
| **Series** | `one` | Amount = genome count | `"amount": "21"` = 21 genome files (each face value 1) |
| **Denomination** | metric denomination | Amount != genome count | `"amount": "21"` = 3 files (face values sum to 21, e.g., 10+10+1) |

> **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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.AskToMoveStream) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/6797b49b412d99eb59e7f303)

### `AskToMoveReq`

| Field | Description |
|-------|-------------|
| `add_settle_time` | Additional settlement time in hours (e.g., "0" for default) |
| `amount` | Total face value of assets to move |
| `app_symbol` | Your App Symbol |
| `note` | Notification details for the Owner |
|         `behavior` | Behavior type for the request (e.g., `move`) |
|         `body` | Message body explaining the request to the Owner |
| `to` | Target Owner user ID to receive the move request |

### `AskToMoveRecord`

| Field | Description |
|-------|-------------|
| `ask_to_move_id` | Unique identifier for this move request |
| `pkg_tag` | Package identifier for tracking the assets |
| `to` | Target Owner user ID |
| `note` | Notification details sent to the Owner |
|         `behavior` | Behavior type for the request |
|         `body` | Message body sent to the Owner |
| `amount` | Total face value of assets requested to move |
| `app_symbol` | Your App Symbol |
| `asset_balance` | Owner's current asset balance (cloud vault only) |
| `notified_at` | Unix timestamp when Owner was notified |
| `status` | Current status of the request (e.g., "OPEN", ) |
| `expires_at` | Unix timestamp when the request expires |
| `behavior_status` | Boolean indicating if behavior is authorized |
| `authorization_status` | Boolean indicating if request is authorized |
| `auth_log_id` | Authentication log identifier for this request |

### Example Request

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

```json
{
    "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",
    "behavior_status": true,
    "authorization_status": true,
    "auth_log_id": "auth-d8042a84-5663-4cb2-94f7-aa61b581f320"
}
```

### Stream Workflow

| Step | Action | Description |
|------|--------|-------------|
| **1. Request** | Appliance sends AskToMoveReq | Initiates the move request with Owner details |
| **2. Notification** | Owner receives notification | Owner is notified via their Onli_You app |
| **3. Response** | Owner accepts/denies | Owner decides whether to approve the move |
| **4. Record** | System returns AskToMoveRecord | Contains request status and tracking information |
| **5. Settlement** | Assets move to locker | If accepted, assets move to settlement locker for the agreed settlement time window; Next step is ChangeOwner rpc |
| **6. Timeout** | Auto-return if unused | Assets return to Owner if not used for ChangeOwner |

### Request Status Values

| Status | Description | Next Steps |
|--------|-------------|------------|
| **ASKED** | Message sent to target owner | Wait for Owner response within 60 seconds |
| **DENIED** | Target owner has denied the request | Request closed, no asset movement |
| **OPEN** | Target owner has accepted the request | Assets available for ChangeOwner |
| **ASKED_EXPIRED** | Target owner did not respond within 60sec window | Request automatically expired |
| **OPEN_EXPIRED** | ChangeOwner did not occur in agreed settlement time window | Package returned to target owner |
| **CLOSED** | Package of genomes has successfully changed ownership | Transfer completed successfully |
| **HOLD** | Administrative block on status change of package | Contact support for resolution |
| **RETURNED** | Master triggered return of package to target owner | Assets returned to original owner |
| **FAILED** | Request failed due to system error | Retry request or contact support |

### 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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.ChangeOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/6797ba0a09772940939b8d3f)

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

### `ChangeOwnerInput`

| Field | Description |
|-------|-------------|
| `from` | Current source and owner user ID (current Owner of the assets) |
| `to` | Recipient destination and owneruser ID (next Owner of the assets) |
| `ask_to_move_id` | Valid AskToMove request ID with "OPEN" status |
| `app_symbol` | Your App Symbol |
| `amount` | Total face value of assets to transfer (must match the amount in the AskToMove request) |
| `which_device` | Destination vault type: "cloud" or "mobile" |

### `ChangeOwnerResponse`

| Field | Description |
|-------|-------------|
| `ask_to_move_id` | The AskToMove request ID that was processed |
| `evolve_id` | Unique identifier for the Transfer Agent's genome editing operation |
| `received_at` | Unix timestamp when request was received |
| `owner_evolved_at` | Unix timestamp when ownership change was processed |
| `delivered_at` | Unix timestamp when assets were delivered to new Owner |

### Example Request

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

```json
{
    "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:

  ```
  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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.ChangeOwner). The table below summarises which classes are safe to retry.

| Error class | Safe to retry? | Notes |
|-------------|----------------|-------|
| `Unavailable` (any client) | Yes | Transient connectivity. Retry with exponential backoff. AskToMove record state is unchanged |
| `Internal` before `EvolveOwner` (e.g. `GetAskToMoveRecord`) | Yes | No state change. Retry |
| `Internal` inside `EvolveOwner` | Conditional | Ownership may have partially transitioned depending on which sub-step failed. Call `GetAskToMoveRecord` and `RevealGenomes` to determine actual state before retrying. If `RevealGenomes` shows the recipient already owns the genomes, the transfer succeeded — do not retry |
| `Internal` `unable to CloseAskToMove` | Conditional | Runs after `EvolveOwner`. The ownership change may have completed even though the AskToMove record was not flipped to `CLOSED`. Reconcile via `GetAskToMoveRecord` and `RevealGenomes` before retrying |
| `Unauthenticated` `askToMoveRecord.Status is not open` | No | Terminal. If status is `CLOSED`, a prior ChangeOwner already succeeded — treat as success. For any other status, a new AskToMove is required |
| `Unauthenticated` `invalid pkg` | No | Package failed validation. A new AskToMove is required |
| `InvalidArgument` (validation, amount mismatch) | No | Fix the request before resubmitting |

**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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.AuthenticateOwner) + [Example](https://www.postman.com/onlicorp/onli/grpc-example/679a51dbde5f880cbcd757b9)

**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`

| Field | Description |
|-------|-------------|
| `owner` | Target Owner user ID to authenticate |
| `app_symbol` | Your App Symbol |
| `body` | Message body explaining the authentication request to the Owner |
| `rev_string` | Master generated string for reverse-mfa authentication (optional) |

### `AuthenticateOwnerRecord`

| Field | Description |
|-------|-------------|
| `owner` | Target Owner user ID that was authenticated |
| `auth_log_id` | Unique identifier for this authentication log entry |
| `authentication_status` | Authentication result status (e.g., "AuthenticationStatusACCEPTED") |
| `auth_type` | Authentication method used (e.g., "BASIC", "REVERSE_MFA") |
| `rev_string` | Master generated string (if reverse-mfa was used) |
| `app_symbol` | Your App Symbol |
| `body` | Message body that was sent to the Owner |
| `asset_balance` | Owner's current asset balance |

### Authentication Methods

| Method | Description | Use Case | Requirements |
|--------|-------------|----------|--------------|
| **BASIC** | Uses owner's gene only | Simple authentication | Owner user ID only |
| **REVERSE_MFA** | Gene + master string | Enhanced security | Owner user ID + rev_string |
| **REVERSE_HASH** | Gene + master nonce | Advanced security | Not currently supported |

### Example Request (Basic Authentication)

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

### Example Response (Basic Authentication)

```json
{
    "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)

```json
{
    "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)

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

| Status | Description | Meaning |
|--------|-------------|---------|
| **ASKED** | Authentication request initiated | Waiting for Owner response |
| **ACCEPTED** | Owner approved authentication | Authentication successful |
| **DENIED** | Owner rejected authentication | Authentication failed |
| **EXPIRED** | Owner did not respond within time limit | Authentication timed out |

### 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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.AuthorizeBehavior) + [Example](https://www.postman.com/onlicorp/onli/grpc-request/679a55540979325625ad5613)

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

### `AuthorizeBehaviorReq`

| Field | Description |
|-------|-------------|
| `owner` | Target Owner user ID to authorize behavior for |
| `app_symbol` | Your App Symbol |
| `note` | Authorization details for the Owner |
|         `behavior` | Specific behavior requesting authorization (e.g., "login", "move") |
|         `body` | Message body explaining the authorization request to the Owner |

### `AuthorizeBehaviorRecord`

| Field | Description |
|-------|-------------|
| `owner` | Target Owner user ID that was asked for authorization |
| `auth_log_id` | Unique identifier for this authorization log entry |
| `authentication_status` | Authorization result status (e.g., "AuthenticationStatusACCEPTED") |
| `app_symbol` | Your App Symbol |
| `note` | Authorization details that were sent to the Owner |
|         `behavior` | Specific behavior that was authorized |
|         `body` | Message body that was sent to the Owner |

### Example Request

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

### Example Response

```json
{
    "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 | Description | Availability |
|----------|-------------|--------------|
| **move** | Asset movement operations | Default on every appliance |
| **BEHAVIOR** | Any desired appliance behavior | Configurable via Appliance Tray APIs |

### 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

| Status | Description | Meaning |
|--------|-------------|---------|
| **ASKED** | Authorization request initiated | Waiting for Owner response |
| **ACCEPTED** | Owner approved behavior | Authorization successful |
| **DENIED** | Owner rejected behavior | Authorization failed |
| **EXPIRED** | Owner did not respond within time limit | Authorization timed out |

### 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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.AuthLog) + [Example](https://www.postman.com/onlicorp/onli/grpc-request/679a4c2bde5f880cbcd74d36)

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

### `AuthLogRequest`

| Field | Description |
|-------|-------------|
| `app_symbol` | Your App Symbol |
| `auth_log_id` | Unique identifier for the auth log entry to retrieve |

### `AuthLogResponse`

| Field | Description |
|-------|-------------|
| `AuthLogId` | The auth log identifier that was requested |
| `TS` | Unix timestamp (nanoseconds) when the event occurred |
| `WhichSecurityMethod` | Security method used (e.g., "ask_to_move_stream", "authenticate_owner") |
| `WhichAppliance` | App symbol of the appliance that triggered the event |
| `GeoData` | Geographic data for the event (may be null) |
| `Request` | JSON string containing the original request data |
| `Response` | JSON string containing the original response data |
| `Err` | Error message if the event failed (empty string if successful) |

### Example Request

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

### Example Response

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

| Method | Description | Log Contains |
|--------|-------------|--------------|
| **ask_to_move_stream** | Asset movement requests | AskToMove request/response data |
| **authenticate_owner** | Owner authentication events | Authentication request/response data |
| **authorize_behavior** | Behavior authorization events | Authorization request/response data |
| **issue** | Asset issuance events | Issue request/response data |
| **change_owner** | Ownership transfer events | ChangeOwner request/response data |

### 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

| Purpose | Description | Benefits |
|---------|-------------|----------|
| **Audit Trail** | Track all authentication/authorization events | Compliance and security monitoring |
| **Debugging** | Review failed transactions and error details | Troubleshooting integration issues |
| **Analytics** | Analyze usage patterns and security events | Business intelligence and optimization |
| **Compliance** | Maintain records for regulatory requirements | Legal and regulatory compliance |

### 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](https://buf.build/onlicorp/onli-cloud/docs/main:onliCloudApi#onliCloudApi.OnliCloudApi.RevealGenomes)

### `RevealGenomesInput`

| Field | Description |
|-------|-------------|
| `search_condition` | The column to search (supports * as wildcard, leave empty for no search) |
| `search_keyword` | Regex supported search query (e.g., "^one\|kilo$") |
| `limit` | Maximum number of records to return (e.g., "1000") |
| `offset` | Number of records to skip (e.g., "0") |
| `sort_by` | Column to sort by (leave empty for no sorting) |
| `sort_order` | Sort direction: "ASC" for ascending, "DESC" for descending |
| `who` | User ID of the owner whose records to reveal |

### `RevealGenomesResponse`

| Field | Description |
|-------|-------------|
| `OracleHelices` | Array of oracle helix records containing genome state information |

#### Oracle Helix Record Fields

| Field | Description |
|-------|-------------|
| `which_onli` | Unique Onli ID identifier for the genome |
| `what_kind` | Asset classification identifier |
| `what_type` | Asset type (e.g., "denomination") |
| `what_face` | Face value of the asset (e.g., "one") |
| `last_owner_id` | Previous owner's user ID |
| `last_owner_name` | Previous owner's display name |
| `current_owner_id` | Current owner's user ID |
| `current_owner_name` | Current owner's display name |
| `blacklisted` | Boolean indicating if the genome is blacklisted |
| `last_updated` | Unix timestamp (nanoseconds) of last update |

### Example Request

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

```json
{
    "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"
        }
    ]
}
```

### Search Capabilities

| Feature | Description | Example |
|---------|-------------|---------|
| **Wildcard Search** | Use * to match any characters | `search_condition: "*"` |
| **Regex Support** | Full regex pattern matching | `search_keyword: "^one\|kilo$"` |
| **Column Filtering** | Search specific fields | `search_condition: "what_face"` |
| **Pagination** | Control result sets with limit/offset | `limit: "100", offset: "200"` |
| **Sorting** | Order results by any field | `sort_by: "last_updated"` |

### Error Handling

| Error Code | Error Message | Reason | Resolution |
|------------|---------------|--------|------------|
| **Unavailable** | unable to initialize GenomeOracleUser client | OCT not able to connect to GenomeOracle | Check Oracle service connectivity |
| **Internal** | unable to get RevealGenomes | Internal error in GenomeOracle | Retry request or contact support |
| **Internal** | unable to find onli_id in oracle database | Internal error in oracle database | Verify owner ID exists and retry |

### 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

| Purpose | Description | Benefits |
|---------|-------------|----------|
| **Asset Verification** | Confirm ownership and authenticity | Trust and security validation |
| **Compliance Tracking** | Monitor asset movement and status | Regulatory compliance support |
| **Portfolio Management** | View and analyze asset holdings | Investment and allocation insights |
| **Audit & Forensics** | Investigate transaction history | Security and dispute resolution |

### 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.