API Reference

Introduction

The API follows REST conventions and returns JSON responses. All requests must include proper authentication headers.

Quick Example

curl -X GET "https://api.netkey.no/api/v1/psks" \
  -H "X-API-Key: nk_abc123..." \
  -H "Content-Type: application/json"

Authentication

NetKey supports two authentication methods: API Keys for programmatic access and JWT tokens for user sessions.

Authentication Methods

API Keys

API keys are recommended for programmatic access. They can be created by Group Admins in the Settings → API Keys section of the dashboard.

Include your API key in the X-API-Key header with every request:

X-API-Key: nk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key Format

API keys follow this format:

• nk_... - API key with a random alphanumeric suffix

JWT Tokens

For web applications and user sessions, NetKey uses JWT access tokens with refresh token rotation. See the Web Authentication Guide for details.

Include the JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key Scopes

API keys can have limited permissions through scopes:

Rate Limits

API requests are rate limited to ensure fair usage and system stability. Rate limits are applied per API key.

Rate Limit Headers

Responses include headers indicating your current rate limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1735200000

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON body with details.

HTTP Status Codes

Error Response Format

{
  "success": false,
  "error": "PSK not found",
  "code": "PSK_NOT_FOUND",
  "details": {
    "psk_id": 123
  }
}

Login

Authenticate a user and receive access and refresh tokens.

Request Body

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "username": "user@example.com",
    "full_name": "John Doe",
    "role": "GROUP_ADMIN",
    "group_id": 3,
    "group_name": "Acme Corp"
  }
}

// Also sets HttpOnly cookie:
Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Lax; Path=/api/auth

MFA Required Response

If MFA is enabled but no TOTP code provided:

{
  "requires_mfa": true,
  "mfa_type": "totp"
}

Refresh Token

Get a new access token using the refresh token cookie. No request body needed.

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

// Rotates the refresh token:
Set-Cookie: refresh_token=new_token...; HttpOnly; Secure; SameSite=Lax; Path=/api/auth

Token Rotation

For security, each refresh request invalidates the old refresh token and issues a new one.

Logout

Invalidate the current session and revoke the refresh token.

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "success": true
}

// Clears the refresh token cookie:
Set-Cookie: refresh_token=; Expires=Thu, 01 Jan 1970; Path=/api/auth

Get Current User

Get the current authenticated user's profile information.

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "id": 1,
  "username": "user@example.com",
  "full_name": "John Doe",
  "role": "GROUP_ADMIN",
  "group_id": 3,
  "group_name": "Acme Corp",
  "email_verified": true,
  "mfa_enabled": true,
  "last_login": "2026-01-07T10:30:00Z",
  "created_at": "2025-06-15T08:00:00Z"
}

List PSKs

Retrieve a list of all PSKs in your group.

Headers

Example Request

curl -X GET "https://api.netkey.no/api/v1/psks" \
  -H "X-API-Key: nk_abc123..."

Example Response

{
  "psks": [
    {
      "id": 1,
      "psk_id": "guest-a1b2c3d4",
      "description": "Guest - John Smith",
      "vlan_id": 100,
      "enabled": true,
      "expires": "2025-12-31T23:59:59",
      "created_at": "2025-01-15T10:30:00"
    }
  ],
  "total": 1
}

Get PSK

Retrieve a specific PSK by ID, including the PSK value.

Path Parameters

Example Request

curl -X GET "https://api.netkey.no/api/v1/psks/1" \
  -H "X-API-Key: nk_abc123..."

Example Response

{
  "id": 1,
  "psk_id": "guest-a1b2c3d4",
  "psk_value": "SecureGuest123",
  "description": "Guest - John Smith",
  "vlan_id": 100,
  "enabled": true,
  "expires": "2025-12-31T23:59:59",
  "created_at": "2025-01-15T10:30:00"
}

Create PSK

Create a new PSK. Useful for guest access, hospitality integrations, etc.

Request Body

Example Request

curl -X POST "https://api.netkey.no/api/v1/psks" \
  -H "X-API-Key: nk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "psk_id": "guest-jane-doe",
    "description": "Guest - Jane Doe",
    "vlan_id": 100,
    "expires_in_hours": 24
  }'

Example Response

{
  "id": 42,
  "psk_id": "guest-jane-doe",
  "psk_value": "Abc123XyzDef",
  "description": "Guest - Jane Doe",
  "vlan_id": 100,
  "expires": "2025-01-21T15:00:00",
  "enabled": true
}

Update PSK

Update an existing PSK.

Request Body

All fields are optional. Only include fields you want to update.

Example Request

curl -X PUT "https://api.netkey.no/api/v1/psks/42" \
  -H "X-API-Key: nk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated guest",
    "vlan_id": 200
  }'

Delete PSK

Delete a PSK. This action cannot be undone.

Example Request

curl -X DELETE "https://api.netkey.no/api/v1/psks/42" \
  -H "X-API-Key: nk_abc123..."

Example Response

{
  "success": true,
  "deleted_id": 42
}

List Endpoints

List all endpoints (devices) for iPSK authentication.

Create Endpoint

Add a new device endpoint for iPSK authentication.

Delete Endpoint

Remove a device endpoint.

List Users

Retrieve all users in your group.

Create User

Create a new user in your group.

Request Body

Request Body (Coming Soon)