Delivery Management API

Manage your Own Auth Delivery apps, settings, keys, and usage programmatically. Everything available in the dashboard is also available through this API.

Base URL

The dashboard equivalents are App Settings, Delivery Keys, Delivery Logs, and usage and billing.

text

https://api.own-auth.com/v1

Authentication

All requests require an account API key in the Authorization header:

http

Authorization: Bearer oa_your_api_key

Create an account API key from the dashboard under Account → API Keys. Account API keys have full access to all apps, settings, and keys in your account.

Apps

To manage apps without the API, use the app switcher in App Settings.

List apps

http

GET /apps

json

{
  "apps": [
    {
      "id": "app_x1y2z3",
      "name": "My Production App",
      "slug": "my-production-app",
      "createdAt": "2026-07-10T14:23:01Z"
    }
  ]
}

Create an app

http

POST /apps

json

{
  "name": "My Production App"
}

Response:

json

{
  "app": {
    "id": "app_x1y2z3",
    "name": "My Production App",
    "slug": "my-production-app",
    "createdAt": "2026-07-10T14:23:01Z"
  }
}

The slug is generated from the name. It is lowercase, hyphenated, and unique.

Get an app

http

GET /apps/:appId

Update an app

http

PATCH /apps/:appId

json

{
  "name": "New App Name"
}

Delete an app

http

DELETE /apps/:appId

Deletes the app, revokes all its keys, and removes access to its settings. Delivery logs are retained for 30 days after deletion. This action is permanent.

Settings

To manage these values without the API, open App Settings.

Get app settings

http

GET /apps/:appId/settings

json

{
  "settings": {
    "linkMode": "hosted",
    "dailySendLimit": 1000,
    "allowedUrls": [],
    "deepLinkScheme": "coparent://app/auth",
    "fallbackUrl": "https://apps.apple.com/app/coparent/id123456789"
  }
}

Field	Type	Description
linkMode	`web` or `hosted`	Use `web` for links to your domain. Use `hosted` for `go.own-auth.com` links that continue through a deep link.
dailySendLimit	number	Maximum emails sent per day for this app.
allowedUrls	string[]	Required in web mode. At least one website root or app scheme must be configured. Auth emails are rejected when their destination does not match one of these values.
deepLinkScheme	string or null	Hosted mode only. The hosted page redirects to this URI with the one-time auth token attached. Custom app schemes require an installed standalone app registered for the scheme.
fallbackUrl	string or null	Hosted mode only. Optional App Store, Play Store, or download URL shown on mobile when the app is not installed.

Your app sends the one-time token from the deep link to its backend. The own-auth package verifies it and creates the session.

Test custom app schemes on a phone or desktop device with the standalone app installed. A mobile app scheme does not open the mobile app from a desktop browser, and Expo Go may not register the scheme. Configure fallbackUrl for mobile users who do not have the app installed.

Update app settings

http

PATCH /apps/:appId/settings

Send only the fields you want to change.

Switch to hosted mode with a deep link:

json

{
  "linkMode": "hosted",
  "deepLinkScheme": "coparent://app/auth",
  "fallbackUrl": "https://apps.apple.com/app/coparent/id123456789"
}

Switch to web mode with at least one allowed website root or app scheme. Web mode rejects every auth email until an allowed URL is configured:

json

{
  "linkMode": "web",
  "allowedUrls": [
    "https://myapp.com",
    "https://staging.myapp.com"
  ]
}

Update the daily send limit:

json

{
  "dailySendLimit": 5000
}

Validation

Field	Rule	Error
linkMode	Must be `web` or `hosted`.	`INVALID_LINK_MODE`
deepLinkScheme	Required when linkMode is `hosted`.	`DEEP_LINK_REQUIRED`
deepLinkScheme	Must be a valid URI.	`INVALID_DEEP_LINK`
allowedUrls	At least one is required when linkMode is `web`.	`ALLOWED_URL_REQUIRED`
allowedUrls	Each value must be a valid URI.	`INVALID_URL`
allowedUrls	Maximum 10.	`TOO_MANY_URLS`
fallbackUrl	Must use HTTPS when provided.	`INVALID_FALLBACK_URL`
dailySendLimit	Integer from 1 to 100,000.	`INVALID_SEND_LIMIT`

Keys

To manage delivery keys without the API, open Delivery Keys.

List keys

http

GET /apps/:appId/keys

json

{
  "keys": [
    {
      "id": "key_a1b2c3",
      "name": "Production",
      "prefix": "oad_...a3f8",
      "createdAt": "2026-07-10T14:23:01Z"
    }
  ]
}

Raw key values are never returned after creation.

Create a key

http

POST /apps/:appId/keys

json

{
  "name": "Production"
}

Response:

json

{
  "key": {
    "id": "key_a1b2c3",
    "name": "Production",
    "prefix": "oad_...a3f8",
    "createdAt": "2026-07-10T14:23:01Z"
  },
  "rawKey": "oad_a8f2c1d9e3b7f4a6..."
}

rawKey is returned once in this response. Store it securely because it cannot be retrieved again.

Revoke a key

http

DELETE /apps/:appId/keys/:keyId

The key stops working immediately.

Rotate a key

http

POST /apps/:appId/keys/:keyId/rotate

Creates a new key and revokes the old one in a single operation.

json

{
  "key": {
    "id": "key_d4e5f6",
    "name": "Production",
    "prefix": "oad_...b7c2",
    "createdAt": "2026-07-11T09:15:00Z"
  },
  "rawKey": "oad_f7e6d5c4b3a2...",
  "revokedKeyId": "key_a1b2c3"
}

Usage

To view usage without the API, open usage and billing.

Get current usage

http

GET /usage

Returns usage for the current billing cycle across all apps.

json

{
  "usage": {
    "plan": "scale",
    "quota": null,
    "used": 12482,
    "remaining": null,
    "cycleStart": "2026-07-01T00:00:00Z",
    "cycleEnd": "2026-07-31T23:59:59Z",
    "apps": [
      { "appId": "app_x1y2z3", "name": "Production", "used": 10200 },
      { "appId": "app_a4b5c6", "name": "Staging", "used": 2282 }
    ]
  }
}

Get daily usage

http

GET /usage/today

Returns today's usage. Billing plans do not impose a daily email limit.

json

{
  "today": {
    "used": 42,
    "limit": null,
    "remaining": null,
    "resetsAt": null
  }
}

Errors

All errors use the same response shape:

json

{
  "error": {
    "code": "INVALID_DEEP_LINK",
    "message": "deepLinkScheme must be a valid URI"
  }
}

HTTP status codes

Status	When
200	Success
201	Resource created
400	Validation error
401	Missing or invalid account API key
403	Account API key does not have permission
404	Resource not found
429	Rate limited

Rate limits

Endpoint	Limit
All endpoints	60 requests per minute per account

Rate-limit headers are included in every response:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1720693200

Full Setup Through the API

Configure a mobile app from scratch with curl:

bash

# Create an app
curl -X POST https://api.own-auth.com/v1/apps \
  -H "Authorization: Bearer oa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CoParent"}'

# Configure hosted mode with a deep link
curl -X PATCH https://api.own-auth.com/v1/apps/app_x1y2z3/settings \
  -H "Authorization: Bearer oa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "linkMode": "hosted",
    "deepLinkScheme": "coparent://app/auth",
    "fallbackUrl": "https://apps.apple.com/app/coparent/id123456789",
    "dailySendLimit": 1000
  }'

# Create a delivery key
curl -X POST https://api.own-auth.com/v1/apps/app_x1y2z3/keys \
  -H "Authorization: Bearer oa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

# Check usage
curl https://api.own-auth.com/v1/usage \
  -H "Authorization: Bearer oa_your_api_key"

SDKs

Use fetch, curl, or any HTTP client.

#Base URL

#Authentication

#Apps

List apps

Create an app

Get an app

Update an app

Delete an app

#Settings

Get app settings

Update app settings

Validation

#Keys

List keys

Create a key

Revoke a key

Rotate a key

#Usage

Get current usage

Get daily usage

#Errors

HTTP status codes

Rate limits

#Full Setup Through the API

#SDKs

Base URL

Authentication

Apps

Settings

Keys

Usage

Errors

Full Setup Through the API

SDKs