Auth & Identities
Authentication endpoints and identity management in the Novacore REST API.
Authentication Endpoints
Request Challenge
POST /auth/challenge
Request a challenge string to sign for authentication.
Request Body:
{
"public_key": "base64-encoded-public-key"
}
Response:
{
"challenge": "random-challenge-string",
"expires_at": "2026-03-06T13:00:00Z"
}
Verify Signature
POST /auth/verify
Submit the signed challenge to receive a JWT token.
Request Body:
{
"public_key": "base64-encoded-public-key",
"signature": "base64-encoded-signature",
"challenge": "the-challenge-string"
}
Response:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"identity_id": "usr-abc123"
}
Identity Types
| Type | Key Algorithm | Description |
|---|---|---|
root | Ed25519 | System administrator |
admin | Ed25519 | Platform administrator |
user | Ed25519 | Human user (developer, operator) |
gateway | ES256 | Zap gateway device |
device | ES256 | Smart device with direct connectivity |
integration | ES256 | Third-party service (monitoring) |
developer | Ed25519 | API developer |
internal | ES256 | Internal service |
Identity Registration
Register a new identity before first authentication:
POST /identity/register
Request Body:
{
"public_key": "base64-encoded-public-key"
}
Knowledge gap for Johan: What fields does identity registration require beyond public_key? Is registration required before /auth/challenge, or does the challenge endpoint auto-register new keys? What is the full response from registration?
OAuth2 (For Integrations)
Novacore supports OAuth2 Authorization Code flow for integrations like Grafana:
| Endpoint | Description |
|---|---|
GET /oauth/authorize | Authorization page |
POST /oauth/authorize/complete | Complete authorization |
POST /oauth/token | Exchange code for token |
GET /oauth/userinfo | Get authenticated user info |
OAuth2 is primarily for internal integrations. External developer applications should use the challenge/verify flow.
MQTT Authentication (Gateways)
Gateways authenticate to NATS/MQTT using ES256 JWTs. This is handled internally by the auth-callout service:
| Internal Endpoint | Description |
|---|---|
POST /internal/mqtt/auth | Validate MQTT connection credentials |
POST /internal/mqtt/acl | Check topic-level access control |
These endpoints are not for external use — they're called by the NATS auth-callout service during gateway connection.
Related Documentation
- Authentication Guide - Full auth flow with code examples
- Organizations API - Manage orgs after authenticating