Developer Apps API

This page documents the dashboard-facing app management routes that exist in the SeloraX backend today.

These are not the same as the app runtime APIs under /api/apps/v1/*.

Authentication and Permissions

These routes use dashboard authentication and usually require some combination of:

authenticated admin session
store ownership checks when store_id is involved
dashboard permissions such as apps__manage_apps or apps__install_apps

The examples below focus on the route shape and payloads. In production, these calls are typically made by the SeloraX admin dashboard itself.

Base Groups

Registry and review

Route	Purpose
`GET /api/apps`	List all apps
`GET /api/apps/marketplace`	Marketplace-ready apps
`GET /api/apps/development`	Current user's development apps
`GET /api/apps/review`	Review queue for app managers
`GET /api/apps/:app_id`	Get one app
`POST /api/apps`	Create app
`PUT /api/apps/:app_id`	Update app
`DELETE /api/apps/:app_id`	Soft-delete app
`POST /api/apps/:app_id/submit-for-review`	Submit for review
`POST /api/apps/:app_id/review`	Approve / reject / move review state
`POST /api/apps/:app_id/rotate-secret`	Rotate client secret
`POST /api/apps/:app_id/generate-signing-key`	Regenerate session signing key
`GET /api/apps/scopes`	List available scopes

Installations

Route	Purpose
`POST /api/apps/installations/direct-install`	Install an approved or developer-owned app on a store
`GET /api/apps/installations?store_id=...`	List installed apps for a store
`POST /api/apps/installations/:installation_id/uninstall`	Uninstall an app from a store

Embedded app session bridge

Route	Purpose
`GET /api/apps/session/embed-params`	Generate iframe URL + initial session token
`POST /api/apps/session/session-token`	Refresh session token for an installed app
`POST /api/apps/session/verify`	Verify an embedded session token with client credentials

App Registry

List Apps

GET /api/apps?page=1&limit=50&category=messaging&search=sms

Returns the dashboard app registry view.

Response shape:

{
  "message": "Apps fetched successfully.",
  "data": [
    {
      "app_id": 2,
      "client_id": "sx_app_...",
      "name": "SeloraX Messaging",
      "slug": "selorax-messaging",
      "short_description": "Automated SMS for order updates",
      "pricing_type": "usage",
      "pricing_amount": 0,
      "category": "messaging",
      "is_listed": 1,
      "is_active": 1,
      "is_verified": 1,
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1
  },
  "status": 200
}

Create App

POST /api/apps
Content-Type: application/json

Required fields:

name
redirect_urls with at least one URL

Common fields:

{
  "name": "My App",
  "slug": "my-app",
  "description": "Full description",
  "short_description": "Short marketplace description",
  "redirect_urls": ["https://example.com/oauth/callback"],
  "requested_scopes": ["read:orders", "read:store", "billing"],
  "app_url": "https://example.com/embed",
  "setup_url": "https://example.com/setup",
  "webhook_url": "https://api.example.com/install",
  "webhook_receive_url": "https://api.example.com/webhooks",
  "webhook_topics": ["order.created", "order.status_changed"],
  "pricing_type": "subscription",
  "pricing_amount": 499,
  "category": "messaging"
}

Response highlights:

{
  "message": "App created successfully. Save the client_secret — it will not be shown again.",
  "data": {
    "app_id": 5,
    "client_id": "sx_app_...",
    "client_secret": "sx_secret_...",
    "session_signing_key": "hex-signing-key",
    "name": "My App",
    "slug": "my-app"
  },
  "status": 200
}

One-time credentials

The raw client_secret and session_signing_key are only returned once. Store them securely.

Update, Delete, and Review

Use:

PUT /api/apps/:app_id to update app fields and optional extension definitions
DELETE /api/apps/:app_id to soft-delete
POST /api/apps/:app_id/submit-for-review to move a developer-owned app into review
POST /api/apps/:app_id/review to set review_status such as approved, in_review, or rejected

The review endpoint accepts:

{
  "review_status": "approved",
  "review_notes": "Looks good"
}

Rotate Secrets

Rotate the OAuth secret:

POST /api/apps/:app_id/rotate-secret

Response:

{
  "message": "Client secret rotated successfully. Save the new secret — it will not be shown again.",
  "data": {
    "client_secret": "sx_secret_..."
  },
  "status": 200
}

Regenerate the embedded-app signing key:

POST /api/apps/:app_id/generate-signing-key

Response:

{
  "message": "Session signing key generated. Save this key — it will not be shown again.",
  "data": {
    "session_signing_key": "hex-signing-key"
  },
  "status": 200
}

Available Scopes

GET /api/apps/scopes

This returns the active scope catalog from the backend so the dashboard can present valid scope choices when building or editing an app.

Installations

Direct Install

POST /api/apps/installations/direct-install
Content-Type: application/json

{
  "app_id": 5,
  "store_id": 22
}

This route:

installs an approved app immediately
reactivates an uninstalled installation if it already exists
grants the app's requested scopes
issues access and refresh tokens
auto-creates declared webhook subscriptions
registers declared extensions for that installation
optionally delivers credentials to the app's webhook_url

Response:

{
  "message": "App installed successfully.",
  "data": {
    "installation_id": 12,
    "app_id": 5,
    "store_id": 22
  },
  "status": 200
}

Who can use direct install

Approved apps can be direct-installed by store admins with app installation permission. Unapproved apps can only be direct-installed by the developer who created them.

List Installed Apps

GET /api/apps/installations?store_id=22

Returns the active installations for the given store, including app summary data and usage metadata such as last_used_at and request_count.

Uninstall

POST /api/apps/installations/:installation_id/uninstall
Content-Type: application/json

{
  "store_id": 22
}

Uninstall does more than flip a status flag. It also:

clears installation tokens
publishes an app.uninstalled event
cancels active or pending app billing charges for that installation
deactivates webhook subscriptions
deactivates extension installations
cleans app metafield values when supported

Embedded App Session Endpoints

Generate Embed Params

GET /api/apps/session/embed-params?app_id=5&store_id=22

Response:

{
  "message": "Embed params generated.",
  "data": {
    "iframe_url": "https://example.com/embed?store_id=22&host=...&timestamp=...&hmac=...",
    "session_token": "eyJ...",
    "expires_in": 600,
    "app_name": "My App"
  },
  "status": 200
}

This is the bridge between the dashboard and an embedded iframe. The URL is HMAC-signed and the session token is short-lived.

Refresh Session Token

POST /api/apps/session/session-token
Content-Type: application/json

{
  "app_id": 5,
  "store_id": 22
}

Response:

{
  "message": "Session token generated.",
  "data": {
    "session_token": "eyJ...",
    "expires_in": 600
  },
  "status": 200
}

Verify Embedded Session Token

POST /api/apps/session/verify
Content-Type: application/json

{
  "session_token": "eyJ...",
  "client_id": "sx_app_...",
  "client_secret": "sx_secret_..."
}

Response:

{
  "message": "Session token verified.",
  "data": {
    "store_id": 22,
    "installation_id": 12,
    "app_id": 5
  },
  "status": 200
}

This endpoint is rate-limited to 300 requests per minute.

Relationship to Runtime APIs

After install, your app should use the runtime APIs under /api/apps/v1/* with:

Authorization: Bearer sx_at_...
or X-Client-Id, X-Client-Secret, and X-Store-Id

Use the dashboard-facing routes on this page for:

app lifecycle management
merchant install and uninstall flows
embedded iframe bootstrap

Use the API Reference for:

orders
products
customers
inventory
billing
app-facing webhooks