Skip to content

partner-onboarding.mdx

Latest commit

 

History

History
231 lines (176 loc) · 9.16 KB

partner-onboarding.mdx

File metadata and controls

231 lines (176 loc) · 9.16 KB
Raw
title Partner Onboarding
description How partners onboard themselves via the Partner Portal, plus the Admin API for scripted/automated onboarding.

SmartphoneKey delivers events to partner systems via webhooks. Most partners onboard themselves through the Partner Portal: sign in with Auth0, copy your API key, set a webhook URL, done. If you need scripted or automated onboarding — or any change beyond the URL (events filter, secret rotation, multiple webhooks) — an Admin API is available and documented further down this page.

Quickstart: Self-Service via the Partner Portal

For partners who already have a SmartphoneKey account in Auth0:

  1. Visit the partner portal for your environment. For example, dev is at https://partner-portal.spk-dev.workers.dev/. (Each environment has its own portal URL — your account manager will share the right one for stage / nonprod / prod.)
  2. Sign in with Auth0. Click Sign in with Auth0 and complete the OIDC flow.
  3. Complete onboarding (first sign-in only). New partners are sent to a short onboarding form to choose an organization ID and name. Submitting it registers your tenant and issues your initial API key.
  4. Copy the API key shown once. The full key is shown only once, on the dashboard, immediately after it's issued — copy and store it in your secret manager now. After that, only a masked prefix is visible.
  5. Set your webhook URL on the dashboard. Enter the HTTPS endpoint in your system that will receive events.
  6. Done — events start arriving. Your webhook is created with status active, and events for your orgId are delivered to your URL.

You can return to the dashboard any time to rotate the API key or update the webhook URL.

See Partner Portal for the full UI walkthrough.

Receiving events

Events arrive at your webhook URL as HTTP POST requests carrying an AWS EventBridge envelope. The detail field includes a partnerId that matches your orgId, so you only receive events for your organization. Failed deliveries are retried automatically.

For payload shapes, delivery authentication, retry behavior, and security best practices, see Setting Up Webhooks and the Event Catalog.

What partners can do without admin help

Action Self-Service (Portal) Admin API
Register tenant + create initial API key Yes (via onboarding form on first sign-in) Yes (POST /tenants/{orgId}/register, then POST /api-keys)
View masked API key Yes Yes (list/get tenants)
Rotate API key Yes Yes
Set/update webhook URL Yes Yes
Update events filter No Yes (admin-only)
Rotate webhook secret No Yes (admin-only)
Multiple webhooks per partner No Yes (admin-only)

Programmatic onboarding (Admin API)

The rest of this page documents the Admin API. Use this for automation, integration tests, or admin operations the portal doesn't cover (events filters, secret rotation, multiple webhooks per partner).

Prerequisites

  • Admin API Key (X-Admin-API-Key) — stored in Doppler as ADMIN_API_KEY
  • Admin JWT Token (Authorization: Bearer <token>) — must have email with @smartphonekey.com domain

Both headers are required on every admin-api request.

Environments

Environment Admin API URL
Dev https://admin-api.spk-dev.workers.dev
Nonprod https://admin-api.spk-nonprod.workers.dev
Stage https://admin-api.spk-stage.workers.dev
Prod https://admin-api.spk-prod.workers.dev

Step 1: Register the Partner (Tenant)

Register the tenant before creating an API key. The orgId is the path segment (acme-corp below).

curl -X POST "https://admin-api.spk-dev.workers.dev/tenants/acme-corp/register" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgName": "ACME Corporation",
    "ownerEmail": "owner@acme-corp.com"
  }'

This must succeed first — POST /api-keys returns 404 Tenant not registered if the tenant doesn't exist yet.

Step 2: Create the API Key

curl -X POST "https://admin-api.spk-dev.workers.dev/api-keys" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "acme-corp",
    "orgName": "ACME Corporation"
  }'

An optional expiresAt (ISO 8601) field is also accepted to issue a time-limited key.

Response: (HTTP 201)

{
  "apiKey": "xK7mP9qR2wT5vN8jL4hG6cF3bA0eD1iY...",
  "orgId": "acme-corp",
  "orgName": "ACME Corporation",
  "createdAt": "2026-04-02T10:00:00.000Z",
  "createdBy": "admin@smartphonekey.com",
  "expiresAt": null
}

Save the apiKey — it won't be shown again (only the prefix is visible in list endpoints).

Notes:

  • One active API key per organization
  • If the org already has an active key, you'll get 409 Conflict
  • The API key is 40 random alphanumeric characters

Step 3: Set Up Webhook

Register a webhook URL to receive events for this partner. See Setting Up Webhooks for full configuration options including authentication and retry behavior.

curl -X POST "https://admin-api.spk-dev.workers.dev/tenants/acme-corp/webhooks" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme-corp.com/webhooks/smartphonekey",
    "events": [
      "LockCreated",
      "KeyAdded"
    ]
  }'

Response:

{
  "success": true,
  "aggregateId": "acme-corp",
  "version": 1
}

Notes:

  • URL must be HTTPS in production (HTTP allowed in dev)
  • A webhook secret is auto-generated if not provided
  • The webhook is backed by AWS EventBridge — events matching the partner's orgId are delivered to the URL

Available Event Types

You can subscribe to any of the spk.api domain event types (e.g. LockCreated, OwnerSet, KeyAdded, KeyRemoved, ResidentAdded, ResidentRemoved, plus User, Hub, Camera, Temp-key and Matter events) as well as Shadow Update (the one type sourced from spk.iot.shadow).

To subscribe to… Pass in events
Specific events The PascalCase detail-type(s), e.g. ["LockCreated", "KeyAdded"]
Everything for your org ["*"] (wildcard)
IoT hub shadow updates ["Shadow Update"]

See Partner Webhooks for the full list of detail-types and the Event Catalog for payload shapes.

Step 4: Verify Webhook

Check that the webhook was created and its status:

curl "https://admin-api.spk-dev.workers.dev/tenants/acme-corp/webhooks" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN"

Response:

{
  "webhooks": [
    {
      "id": "32bc72f9-1676-4cd5-b568-15a39a80536e",
      "url": "https://acme-corp.com/webhooks/smartphonekey",
      "events": ["LockCreated", "KeyAdded"],
      "status": "active",
      "createdAt": "2026-04-02T10:01:00.000Z"
    }
  ],
  "total": 1
}

(Response abbreviated — each webhook also includes verifiedAt, updatedAt, and last-error fields, and the top level includes limit/offset.)

A newly created webhook is active immediately. If you later change its URL, the status resets to pending until the new endpoint is re-verified.

Updating a Webhook

curl -X PUT "https://admin-api.spk-dev.workers.dev/tenants/acme-corp/webhooks/WEBHOOK_ID" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme-corp.com/webhooks/v2",
    "events": ["LockCreated", "KeyAdded"]
  }'

At least one field (url, events, or secret) must be provided.

Deleting a Webhook

curl -X DELETE "https://admin-api.spk-dev.workers.dev/tenants/acme-corp/webhooks/WEBHOOK_ID" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN"

Listing Partners

curl "https://admin-api.spk-dev.workers.dev/tenants" \
  -H "X-Admin-API-Key: $ADMIN_API_KEY" \
  -H "Authorization: Bearer $ADMIN_JWT_TOKEN"

How Events Flow to Webhooks

  1. An action happens in the B2C API (e.g., lock opened, key assigned)
  2. The event is published to AWS EventBridge with source: "spk.api" and partnerId matching the lock's organization
  3. EventBridge matches the event against webhook subscription rules
  4. The event is delivered to the partner's webhook URL

Events include partnerId in the detail so partners receive only events for their organization.

Next Steps

  • Partner Portal — Self-service UI for partners to view their key and update their webhook URL
  • Events Overview — Understand how SmartphoneKey publishes events via EventBridge
  • Setting Up Webhooks — Full webhook configuration: authentication, delivery, retry behavior, and security best practices
  • Event Catalog — Complete reference for the highest-value event payloads