OAuth Authentication

Overview

Omi uses an OAuth 2.0-like flow to allow third-party applications to access user data with explicit consent. This ensures users maintain control over their data and what applications can access.

User Consent

Users explicitly approve what data your app can access

Secure Token Exchange

Firebase authentication ensures secure identity verification

Prerequisites

Before implementing OAuth, ensure you have:

Your app must be registered with Omi and have an App ID

Configure App Home URL

Set your App Home URL in your app’s settings - this is where users are redirected after authorization

HTTPS Required

Your App Home URL must use HTTPS

OAuth Flow

Redirect User to Omi

Your app redirects the user to Omi’s authorization endpoint:

https://api.omi.me/v1/oauth/authorize?app_id=YOUR_APP_ID&state=YOUR_STATE

Parameter	Required	Description
`app_id`	Yes	Your application’s unique ID
`state`	No	Opaque value for CSRF protection and maintaining state

Always use the state parameter to prevent CSRF attacks. Generate a random string and verify it when the user returns.

User Authenticates & Consents

On the Omi authorization page, the user:

Logs in with their Firebase credentials (Google or Apple)
Reviews the permissions your app is requesting
Grants or denies access

Example permissions shown to users:

“Engage in chat conversations with Omi”
“Access and manage your conversations”
“Process audio data in real-time”
“Create new conversations on your behalf”
“Access and read your stored memories”

Token Exchange

After user approval, Omi’s authorization page handles the token exchange internally:

POST https://api.omi.me/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

firebase_id_token=FIREBASE_TOKEN&app_id=YOUR_APP_ID&state=YOUR_STATE

Response:

{
  "uid": "USER_UNIQUE_ID",
  "redirect_url": "YOUR_APP_HOME_URL",
  "state": "YOUR_STATE_IF_PROVIDED"
}

This step is handled automatically by Omi’s authorization page - you don’t need to implement this yourself.

User Redirected to Your App

The user’s browser is redirected to your App Home URL with query parameters:

https://your-app.com/callback?uid=USER_UNIQUE_ID&state=YOUR_STATE

Your app should:

Validate the state parameter matches what you sent
Store the uid for making API calls on behalf of the user

Handling the Callback

Example implementation for handling the OAuth callback:

Python (FastAPI)
Node.js (Express)

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import RedirectResponse
import secrets

app = FastAPI()

# Store state tokens (use Redis in production)
pending_states = {}

@app.get("/start-oauth")
async def start_oauth():
    # Generate CSRF token
    state = secrets.token_urlsafe(32)
    pending_states[state] = True

    # Redirect to Omi
    return RedirectResponse(
        f"https://api.omi.me/v1/oauth/authorize"
        f"?app_id=YOUR_APP_ID&state={state}"
    )

@app.get("/callback")
async def oauth_callback(uid: str, state: str):
    # Validate state
    if state not in pending_states:
        raise HTTPException(400, "Invalid state parameter")

    del pending_states[state]

    # Store uid for this user's session
    # Now you can make API calls with this uid
    return {"message": f"Successfully connected! User ID: {uid}"}

const express = require('express');
const crypto = require('crypto');

const app = express();
const pendingStates = new Map();

app.get('/start-oauth', (req, res) => {
  // Generate CSRF token
  const state = crypto.randomBytes(32).toString('hex');
  pendingStates.set(state, true);

  // Redirect to Omi
  res.redirect(
    `https://api.omi.me/v1/oauth/authorize` +
    `?app_id=YOUR_APP_ID&state=${state}`
  );
});

app.get('/callback', (req, res) => {
  const { uid, state } = req.query;

  // Validate state
  if (!pendingStates.has(state)) {
    return res.status(400).send('Invalid state parameter');
  }

  pendingStates.delete(state);

  // Store uid for this user's session
  res.send(`Successfully connected! User ID: ${uid}`);
});

Automatic App Enablement

When a user completes the OAuth flow, Omi automatically attempts to enable your app for them.

Enablement Checks

Omi performs several checks before enabling:

Check	Description
Privacy	If app is private, only owner/testers can enable
Setup Completion	If `setup_completed_url` is configured, it must return `true`
Payment	If app is paid, user must have active subscription

If any check fails, the OAuth flow halts and shows an error to the user.

Setup Completion Check

If your app requires setup (e.g., connecting to external services), configure a setup_completed_url:Request from Omi:

GET https://your-app.com/setup-status?uid=USER_ID

Expected Response:

{
  "is_setup_completed": true
}

Return false if the user hasn’t completed setup yet. Omi will show an appropriate message.

Install Count

When a user successfully enables your public app through OAuth, the public install count is incremented (if applicable).

App Configuration

App ID

Unique identifier for your app, provided when you register

App Home URL

Where users are redirected after authorization (must be HTTPS)

Configure these settings in the Omi developer portal or during app submission:

Field	Location	Description
App ID	Auto-generated	Your unique application identifier
App Home URL	`external_integration.app_home_url`	Callback URL after OAuth (HTTPS required)
Setup Completed URL	`external_integration.setup_completed_url`	Optional endpoint to verify user setup

Security Best Practices

Always Use State

Generate a cryptographically random state parameter and validate it on callback to prevent CSRF attacks

Validate Origin

Ensure the uid came from a legitimate OAuth flow, not a forged request

Secure Storage

Store user uid values securely, treating them as sensitive credentials

HTTPS Only

Always use HTTPS for your App Home URL and all API communications

Never expose your App ID in client-side code where it could be extracted. While the App ID itself isn’t secret, it should be treated as sensitive for your integration’s integrity.

Troubleshooting

User not redirected back

Possible causes:

App Home URL not configured or incorrect
App Home URL doesn’t use HTTPS
User denied permissions

Solution: Verify your App Home URL in the developer portal

State parameter mismatch

Possible causes:

State expired before user completed flow
State not properly stored server-side
CSRF attack attempt

Solution: Implement proper session/state management with reasonable expiration

Setup completion check failing

Possible causes:

setup_completed_url returning false or error
Endpoint not accessible from Omi servers
JSON response malformed

Solution: Test your endpoint directly and check server logs

Integration Apps

Build webhook-based integrations

Chat Tools

Add custom tools to Omi chat

Notifications

Send push notifications to users

Submit Your App

Publish your app to the store

Get Started

Core Development

Developer API

MCP Integration

Build Apps

Hardware

DIY Guide

Info

OAuth Authentication

Overview

User Consent

Secure Token Exchange

Prerequisites

OAuth Flow

Handling the Callback

Automatic App Enablement

App Configuration

App ID

App Home URL

Security Best Practices

Always Use State

Validate Origin

Secure Storage

HTTPS Only

Troubleshooting

Integration Apps

Chat Tools

Notifications

Submit Your App

Get Started

Core Development

Developer API

MCP Integration

Build Apps

Hardware

DIY Guide

Info

​Overview

User Consent

Secure Token Exchange

​Prerequisites

​OAuth Flow

​Handling the Callback

​Automatic App Enablement

​App Configuration

App ID

App Home URL

​Security Best Practices

Always Use State

Validate Origin

Secure Storage

HTTPS Only

​Troubleshooting

​Related Documentation

Integration Apps

Chat Tools

Notifications

Submit Your App

Overview

Prerequisites

OAuth Flow

Handling the Callback

Automatic App Enablement

App Configuration

Security Best Practices

Troubleshooting

Related Documentation