---
title: "API Requirements"
description: "Developer credentials and setup requirements for the Onli Platform API"
author: "Onli Platform"
date: "2024-01-01"
tags: ["api", "requirements", "credentials"]
---

# API Requirements
This guide covers the essential requirements for integrating with the Onli Platform APIs. You'll need developer credentials, proper gRPC setup, authentication metadata, and specific configurations for TLS and testing tools. The platform uses gRPC for all API communication and requires specific metadata for authentication on each request.

## Developer Credentials
Developers receive all credentials through the web portal at [OnliCloud.com](https://onlicloud.com).

<Callout type="info">
`app_key` and`app_symbol` will all be available after appliance registration by the appliance owner on [OnliCloud.com](https://onlicloud.com).

Your Onli ID URL is the `env` (aka `deployment_subdomain`) in the subdomain of `ENV.onli.network`. E.g. `dev.onli.network`

Your Onli Cloud URL is the `app_symbol` in the subdomain of an Onli ID URL, such as `APP_SYMBOL.env.onli.app`. E.g. `engma.dev.onli.app`
</Callout>

## gRPC
**[gRPC](https://grpc.io)** Remote Procedure Calls - are the interface of the Onli One Network and your Onli Cloud instance.

RPCs are flexible, fast and reliable. And its protobuf framework is extensible enough that any Appliance technology can integrate with it. Become familiar with RPCs, because it is how you communicate with the Onli Cloud and Onli One Network.

This API framework also lets us develop with natural human language to grasp and interact with Owners and Assets. What this means is that every call is named what it does and can be used without the need to delve into documentation.

Get started [here](https://grpc.io/docs/what-is-grpc/) to lean more.

## TLS Configuration

Onli Cloud APIs use **mutual TLS (mTLS)** for secure, authenticated communication. gRPC clients require an `app_key` along with an mTLS client certificate and key.

<Callout type="info">
Your mTLS client certificate and key are available in the appliance connection details on [OnliCloud.com](https://onlicloud.com).
</Callout>

## API Authentication

All API requests require authentication using gRPC metadata. You must include the following metadata attribute with every request:

<Callout type="info">
`app_key` - Your Appliance API key (obtained from the web portal)
</Callout>

This credential authenticates your appliance for each API call and is provided when you register your appliance on [OnliCloud.com](https://onlicloud.com).

## Anything else?
Our API Reference uses `ENGMA` (`app_symbol`) as the appliance we're developing for. So, anytime you see Enigma, know that it is just a placeholder for your appliance.

### Clear & OnliYou
When developing in non-production environments, the OnliYou app uses the **Clear sandbox** from [ClearMe](https://clearme.com) for identity verification during owner creation and vault initialization.

### Postman
**Important:** Postman only supports gRPC methods in the desktop application, not the web version. 

To get started with our APIs:
1. **Download** the [Postman Desktop App](https://www.postman.com/downloads/)
2. **Fork** the [Onli Cloud and Onli ID API collections](https://www.postman.com/onlicorp/onli/overview) to your workspace
3. **Experiment** with the provided examples and modify them for your use case

This setup allows you to test all gRPC endpoints and explore the API functionality interactively.

### OnliYou iOS Limitations
**Known Issue:** OnliYou iOS background processes may fail when:
- The iOS device is in **hotspot mode** (sharing internet connection)
- **Remote recording** is active from another device (e.g., QuickTime screen recording)

These iOS system features can interfere with background processing. For reliable testing, disable hotspot mode and stop any remote recording sessions before using OnliYou.

### Appliance Tray Services
For appliance tray services, use your **Onli ID URL** for API connections. The complete API schema and service definitions are available at [buf.build/onlicorp/appliance-tray-public](https://buf.build/onlicorp/appliance-tray-public).

This repository contains the protobuf definitions and generated code for all appliance tray service endpoints.