Quickstart

Go from zero to your first Novacore API call in minutes.

This guide walks you through authenticating with Novacore and making your first API call.

Prerequisites

  • An HTTP client (curl, Postman, or your language of choice)
  • An Ed25519 key pair (we'll generate one below)
  • Access to the Novacore testnet

Knowledge gap for Tobias/Johan: Is testnet open for self-service registration, or do developers need to be manually provisioned? Update this section with the actual onboarding flow.

Step 1: Generate a Key Pair

You need an Ed25519 key pair to authenticate. Generate one using Python:

from nacl.signing import SigningKey
import base64

# Generate a new key pair
signing_key = SigningKey.generate()
public_key = base64.b64encode(
    signing_key.verify_key.encode()
).decode()
private_key = base64.b64encode(
    signing_key.encode()
).decode()

print(f"Public key:  {public_key}")
print(f"Private key: {private_key}")

Or using Node.js:

npx @noble/ed25519 # or use the @noble/ed25519 library

Save your private key securely. You'll need it for every authentication. Never share it or commit it to source control.

Step 2: Register Your Identity

curl -X POST https://novacore-testnet.sourceful.dev/identity/register \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "YOUR_PUBLIC_KEY"
  }'

Step 3: Authenticate

Request a challenge and sign it:

# Get a challenge
curl -X POST https://novacore-testnet.sourceful.dev/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "YOUR_PUBLIC_KEY"
  }'

# Sign the challenge with your private key (see Authentication docs for code)
# Then verify:
curl -X POST https://novacore-testnet.sourceful.dev/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "YOUR_PUBLIC_KEY",
    "signature": "YOUR_SIGNATURE",
    "challenge": "THE_CHALLENGE_STRING"
  }'

You'll receive a JWT token in the response. Save it — you'll use it for all API calls.

Step 4: List Your Organizations

curl https://novacore-testnet.sourceful.dev/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Step 5: Create an Organization

curl -X POST https://novacore-testnet.sourceful.dev/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Energy Lab"
  }'

Step 6: Create a Site

curl -X POST https://novacore-testnet.sourceful.dev/sites \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "YOUR_ORG_ID",
    "name": "Home"
  }'

Step 7: Stream Real-time Data (optional)

If you have devices connected, stream telemetry via SSE:

curl -N https://novacore-testnet.sourceful.dev/stream/sites/YOUR_SITE_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Knowledge gap for Johan: Verify the exact endpoint paths, request/response formats, and field names used above. The examples are based on Novacore repo documentation but may need adjustment.

Next Steps