Gateway Claiming

Step-by-step guide to claiming a Zap gateway into your organization.

Claiming binds a physical Zap gateway to your organization, allowing it to relay device data to Novacore.

Prerequisites

  • A Zap gateway powered on and connected to WiFi
  • An authenticated Novacore account with an organization
  • Network access to the Zap (same WiFi network or BLE range)

Step 1: Get Gateway Identity

Connect to the Zap's local API to retrieve its public key and serial number:

curl http://<zap-ip>/api/crypto

Response:

{
  "deviceName": "software_zap",
  "serialNumber": "zap-04772a97",
  "publicKey": "04a1b2c3..."
}

Find the Zap's IP address from your router's DHCP client list, or use the Sourceful mobile app which discovers Zaps via BLE.

Step 2: Sign the Claim Message

The claim requires a message signed by the gateway's private key. Use the Zap's signing endpoint:

curl -X POST http://<zap-ip>/api/crypto/sign \
  -H "Content-Type: application/json" \
  -d '{
    "message": "your-identity-id|nonce|timestamp|zap-04772a97"
  }'

Response:

{
  "message": "your-identity-id|nonce|timestamp|zap-04772a97",
  "sign": "base64-encoded-es256-signature"
}

Step 3: Claim the Gateway

Call the Novacore claim endpoint with the signed message:

curl -X POST https://novacore-mainnet.sourceful.dev/gateways/claim \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org-abc123",
    "gateway_serial": "zap-04772a97",
    "public_key": "04a1b2c3...",
    "message": "your-identity-id|nonce|timestamp|zap-04772a97",
    "signature": "base64-encoded-es256-signature"
  }'

Step 4: Verify

List gateways in your org to confirm:

curl https://novacore-mainnet.sourceful.dev/gateways?org_id=org-abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

The gateway should appear in the response and will begin authenticating its MQTT connection to Novacore.

Reclaiming a Gateway

If you claim a gateway that's already claimed by another org:

  • Ownership transfers to your org
  • Devices become orphaned in the old org (data preserved but disconnected)
  • DERs are NOT migrated — you'll need to provision new DERs in your org
  • The reclaim is silent (the old org is not notified, but an audit event is logged)
  • Same-org reclaim is a no-op (idempotent)

Troubleshooting

IssueSolution
Can't reach Zap local APIVerify Zap is connected to WiFi via /api/wifi or check router DHCP
Signature verification failsEnsure the message format matches exactly: claimer_id|nonce|timestamp|serial
Gateway not appearing after claimWait 30 seconds for the gateway to re-authenticate its MQTT connection

Knowledge gap for Johan: Verify the exact claim message format. Is the nonce generated client-side or server-side? Is the timestamp a Unix epoch or ISO string? What is the exact POST /gateways/claim response?

Next Steps