Developer Guide

Step-by-step guide to building on Omen — from zero to shipping

Contents

  1. Overview — What You Can Build
  2. Getting Started
  3. Create Your Organization & App
  4. Login with Omen (OAuth2)
  5. Store & Retrieve User Data
  6. Items & Badges
  7. Send Notifications
  8. Webhooks
  9. Accept Payments (Stripe Connect)
  10. Avatar Editor
  11. Family & Child Accounts
  12. Publishing Creations
  13. Support Tickets
  14. Full API Reference

Overview — What You Can Build

Omen is a platform for kids and creators. As a developer, you can build apps and games that plug into the Omen ecosystem. Your app gets access to:

  • User accounts — sign users in with "Login with Omen" (OAuth2)
  • User data storage — store per-user and per-org JSON data on Omen's servers
  • Items & badges — issue collectible items and badges to users
  • Notifications — send push and in-app notifications
  • Payments — sell products and subscriptions via Stripe (money goes directly to you)
  • Avatar editor — let users customize avatars using your art assets
  • Webhooks — receive real-time events about item transfers, purchases, etc.
  • Family safety — child accounts have parental approval built in

Getting Started

You need an Omen account with developer access to use the Developer Portal.

1Create an Omen account at omen.dog. Sign up with email or wallet.

2Get developer access. Developer access is currently invite-only. Contact the Omen team or request access through your account settings. Once granted, you'll see the Developer Portal in your Omen menu.

3Open the Developer Portal at /pound/developer. This is your home base for managing organizations, apps, and tools.

Create Your Organization & App

Every app on Omen belongs to an organization. Organizations group apps together and control shared settings like badges and PFP projects.

1Create an Organization. In the Developer Portal, click "Create Organization". Give it a name (you can change it later). This represents your studio, team, or project.

2Create an App. Click "Create App". The app is automatically linked to your first organization. You can change which org it belongs to in the app settings.

3Note your credentials. On the app detail page, you'll see:

  • Client ID — public identifier, safe to use in frontend code
  • Client Secret — keep this on your server, never expose it publicly

4Add Redirect URIs. These are the URLs Omen will redirect users back to after login. Add at least one (e.g. https://myapp.com/callback). For local development, you can use http://localhost:3000/callback.

Tip: You can regenerate your client secret at any time from the app detail page. The old secret will stop working immediately.

Login with Omen (OAuth2)

"Login with Omen" lets your users sign into your app using their Omen account. It uses standard OAuth2 authorization code flow.

How it works

  1. Redirect the user to Omen's authorize page:
    https://omen.dog/api/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code
  2. User logs in & approves. Omen redirects them back to your redirect URI with a code parameter.
  3. Exchange the code for tokens on your server:
    POST https://omen.dog/api/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "THE_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "YOUR_REDIRECT_URI"
}
  4. Use the access token to call Omen APIs on behalf of the user:
    GET https://omen.dog/api/v1/profile
Authorization: Bearer ACCESS_TOKEN
Ready-made buttons: See the Login with Omen Kit for button assets and a copy-paste integration guide.

Store & Retrieve User Data

Store arbitrary JSON data per user in your app. Useful for game saves, preferences, progress, or anything else. Data is scoped to your app — other apps can't see it.

// Read user's data for your app (OAuth2 Bearer auth)
GET /api/v1/app-data
→ { "level": 5, "coins": 120, ... }

// Write user's data (merges with existing)
POST /api/v1/app-data
{ "level": 6, "coins": 200 }

// Server-to-server: read/write any user's data
GET /api/v1/apps/{appId}/users/{userId}/data
POST /api/v1/apps/{appId}/users/{userId}/data

There's also Org Data for data shared across all apps in your organization:

GET /api/v1/org-data
POST /api/v1/org-data

Items & Badges

Issue collectible items and badges to users. Items appear in the user's inventory on their Omen profile.

Setup

  1. Create an Item Template via the API. Templates define what the item looks like, its rarity, whether it's transferable, etc.
    POST /api/v1/apps/{appId}/item-templates
Authorization: Bearer S2S_TOKEN
{
  "type": "collectible",
  "name": "Gold Trophy",
  "description": "Awarded for winning the tournament",
  "imageUrl": "https://cdn.example.com/trophy.png",
  "rarity": "rare",
  "maxSupply": 100,
  "transferable": true
}
  2. Issue items to users when they earn them:
    POST /api/v1/apps/{appId}/items
Authorization: Bearer S2S_TOKEN
{ "userId": "USER_ID", "templateId": "TEMPLATE_ID" }
  3. Check a user's inventory:
    GET /api/v1/apps/{appId}/items?userId=USER_ID
Items can also be auto-issued on purchase if you link a templateId to a checkout product. See the Payments section below.

Send Notifications

Send push and in-app notifications to your users.

POST /api/v1/apps/{appId}/notifications/send
Authorization: Bearer S2S_TOKEN
{
  "userId": "USER_ID",
  "title": "You won!",
  "body": "You placed first in this week's tournament",
  "actionUrl": "https://myapp.com/results",
  "category": "achievement"
}

Notifications show up in the user's notification center on Omen and as push notifications if they've enabled them. Rate limits apply (check the API reference for details).

Webhooks

Receive real-time HTTP callbacks when things happen — items transferred, purchases completed, subscriptions renewed.

Setup

  1. Register a webhook endpoint:
    POST /api/v1/apps/{appId}/webhooks
Authorization: Bearer S2S_TOKEN
{
  "url": "https://myapp.com/webhooks/omen",
  "events": ["item.issued", "checkout.completed", "subscription.created"]
}

    You'll receive a secret in the response — save it to verify incoming webhooks.

  2. Handle incoming webhooks. Omen sends POST requests with:
    • X-Omen-Signature header — HMAC-SHA256 of the body using your secret
    • X-Omen-Event header — the event type
    • JSON body with the event payload

Available events

item.issued           — Item issued to a user
item.revoked          — Item revoked
item.expired          — Item expired (TTL)
item.transferred      — Item transferred between users
redeem.completed      — Redeem code used
checkout.completed    — One-time payment completed
checkout.cancelled    — Checkout session expired
checkout.denied       — Parent denied child purchase
subscription.created  — New subscription activated
subscription.renewed  — Subscription renewed
subscription.cancelled — Set to cancel at period end
subscription.expired  — Subscription ended
subscription.payment_failed — Payment failed

Accept Payments (Stripe Connect)

Sell products and subscriptions to your users. Payments go directly to your Stripe account — Omen takes 0% platform fee. You connect your own Stripe account, Stripe handles all compliance and payouts.

Step 1: Connect your Stripe account

  1. Open the Developer Portal and go to your app
  2. Scroll to the Payments section
  3. Click "Connect Stripe Account"
  4. You'll be redirected to Stripe to create or link an account
  5. Complete the Stripe onboarding (business info, bank account, etc.)
  6. When you're done, you'll be redirected back to the Developer Portal
  7. The Payments section will show Connected with your Stripe account ID
Don't have a Stripe account? Stripe will create one for you during onboarding. You'll need to provide basic business information and a bank account for payouts. Stripe handles all tax compliance, refunds, and dispute management through your Stripe Dashboard.

Step 2: Create products

Products are created via the server-to-server API. Each product is synced to your connected Stripe account automatically.

One-time purchase (e.g. a premium skin, level pack):

POST /api/v1/apps/{appId}/products
Authorization: Bearer S2S_TOKEN
{
  "name": "Premium Skin Pack",
  "type": "one_time",
  "priceCents": 499,
  "templateId": "clx..."  // optional: auto-issue an item on purchase
}

Subscription (e.g. monthly pass):

POST /api/v1/apps/{appId}/products
Authorization: Bearer S2S_TOKEN
{
  "name": "Pro Monthly",
  "type": "subscription",
  "priceCents": 999,
  "billingInterval": "month",
  "trialDays": 7
}

Step 3: Trigger checkout from your app

When a user clicks "Buy" in your app, create a checkout session using their OAuth2 token. The user will be redirected to Stripe's checkout page.

// Your app's frontend
const res = await fetch('https://omen.dog/api/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer USER_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'PRODUCT_ID',
    redirectUrl: 'https://myapp.com/store'
  })
});

const { checkoutUrl, status, requiresParentApproval } = await res.json();

if (requiresParentApproval) {
  // Show "waiting for parent approval" message
  // Parent gets notified via email + in-app notification
} else {
  // Redirect user to Stripe checkout
  window.location.href = checkoutUrl;
}

// After payment, user is redirected back to:
// https://myapp.com/store?checkout=success
// or
// https://myapp.com/store?checkout=cancel

Step 4: Handle the result

After payment, Omen fires a webhook to your server. Set up a webhook endpoint (see Webhooks above) and listen for these events:

  • checkout.completed — payment succeeded, unlock the content
  • subscription.created — subscription started
  • subscription.renewed — subscription auto-renewed
  • subscription.expired — subscription ended, revoke access
Auto-issue items: If you set a templateId on your product, Omen automatically issues the linked item to the buyer when payment completes. No webhook handling needed for simple unlocks.

Managing subscriptions

Users can cancel and resume their subscriptions through the Omen API:

// List user's subscriptions to your app
GET /api/v1/checkout/subscriptions
Authorization: Bearer USER_ACCESS_TOKEN

// Cancel at period end
POST /api/v1/checkout/subscriptions?subscriptionId=xxx&action=cancel

// Resume (if still in active period)
POST /api/v1/checkout/subscriptions?subscriptionId=xxx&action=resume

Refunds and disputes are managed through your Stripe Dashboard directly.

Avatar Editor

The Avatar Editor lets users customize avatars using art assets you provide. You host an API that serves your art layers, and Omen renders the editor UI.

Setup

  1. Build an avatar API server that serves your art assets. See the full Avatar Editor API spec for the required endpoints.
  2. Add a PFP Project to your app. In the Developer Portal, open your app, scroll to PFP Projects, and click "Add PFP Project". Enter your API's base URL and an API key if your server requires one.
  3. Test it by clicking "Open Editor" next to your project. The editor will load your art assets and let you compose avatars.

When a user saves their avatar, Omen stores the composed image and the selection data. Your app can read the user's avatar via the profile API.

PFP Projects and Organizations: If your app is linked to an organization, PFP projects are managed at the org level (shared across all apps in the org). You'll see a link to manage them in the Organization settings.

Family & Child Accounts

Omen supports child accounts managed by a parent. If your app's users include children, here's what you need to know:

  • Purchases require parent approval. When a child tries to buy something, the checkout session enters awaiting_parent_approval state. The parent gets an email and in-app notification. Your app should show a "waiting for parent" message and poll the session status.
  • Check if a user is a child via the profile API. The isChild field will be 1 if the user is a child account.
  • Children log in via QR code generated by the parent — they don't use email or wallet login. From your app's perspective, the OAuth flow is the same.
  • Notifications to parents: When you send notifications to a child user, the parent is also notified automatically for certain event types.

You don't need to build any special family logic — Omen handles it. Just be aware that checkout flows may pause for parent approval, and design your UI to handle that gracefully.

Publishing Creations

Omen Publish lets you deploy web games, apps, and interactive content to Omen user profiles. Published creations are hosted on Omen's CDN and accessible via the user's profile page.

Setup

  1. Install the CLI:
    npm install -g omen-publish
  2. Build your project as a static site (HTML/CSS/JS).
  3. Publish:
    omen-publish ./dist
    The CLI will scan your files, run security checks, and deploy to Omen.

For more details, see the Publish Pipeline docs in the API reference.

Support Tickets

Users can submit support tickets about your app through Omen. View and manage tickets in the Developer Portal under Tickets.

Tickets are visible at /pound/developer/tickets.

Full API Reference

This guide covers the setup flow and common patterns. For complete endpoint documentation with all parameters, response shapes, and edge cases, see the full API reference.

Additional references: