Skip to main content

API Keys & Machine-to-Machine (M2M) Tokens

NodeStack provides high-entropy API Keys for headless services, automated workers, serverless functions, and CI/CD pipelines.


Key Format & Security Architecture​

API keys follow a structured, cryptographically secure format:

Format: nsk_<env>_<keyId>_<secretEntropy>
Example: nsk_live_k8f9a2_9e3d81b2c45f7801a34b82c1e7d904ab92d4ef0a8c12...
└──┬──┘ └──┬──┘ └──┬───┘ └──────────────────┬─────────────────┘
Prefix Env Key ID Secret Entropy (48 hex)
  • Zero Plaintext Storage: The full key is displayed only once upon generation. The database stores only an indexed lookup prefix (nsk_live_k8f9a2), a redacted hint, and a SHA-256 hash.
  • Side-Channel Protection: Hashes are verified using constant-time crypto.timingSafeEqual.
  • In-Memory Cache: Active keys are cached in memory with a short TTL for sub-millisecond request verification.

Creating & Managing API Keys​

Via REST API (Superuser)​

Create an API Key​

curl -X POST http://localhost:8090/api/api-keys \
-H "Authorization: Bearer <ADMIN_JWT>" \
-H "Content-Type: application/json" \
-d '{
"name": "Inventory Worker",
"description": "Background sync daemon",
"role": "service",
"scopes": ["orders:read", "products:*"],
"allowedIps": ["10.0.0.0/24", "127.0.0.1"],
"expiresInDays": 90
}'

Response:

{
"apiKey": {
"id": "key_k8f9a2_31107e",
"name": "Inventory Worker",
"keyPrefix": "nsk_live_k8f9a2",
"redactedKey": "nsk_live_k8f9a2...04ab",
"role": "service",
"scopes": ["orders:read", "products:*"],
"status": "active",
"expiresAt": "2027-01-23T12:00:00.000Z"
},
"secretKey": "nsk_live_k8f9a2_9e3d81b2c45f7801a34b82c1e7d904ab..."
}

Rotate an API Key​

Atomically invalidates the old secret, generates new secret entropy, and returns the new key:

curl -X POST http://localhost:8090/api/api-keys/key_k8f9a2_31107e/rotate \
-H "Authorization: Bearer <ADMIN_JWT>"

Revoke / Delete an API Key​

curl -X DELETE http://localhost:8090/api/api-keys/key_k8f9a2_31107e \
-H "Authorization: Bearer <ADMIN_JWT>"

Granular Read/Write ACL & Scoping Syntax​

Scopes use the format <resource>:<action>:

Scope PatternPermissions Granted
* or admin:*Full unrestricted superuser access (bypasses all collection rules).
orders:*Full access (list, view, create, update, delete, export, import) on orders.
orders:readRead-only access (list, view, export) on orders.
orders:writeMutation access (create, update, delete, import) on orders.
orders:createOnly permitted to create new records in orders.

If a key attempts an operation outside its assigned scopes, NodeStack returns 403 Forbidden with a detailed error message:

{
"statusCode": 403,
"message": "API Key missing required scope for 'orders:create'"
}

Using API Keys in Client Applications​

With nodestack-client​

Pass the apiKey directly when instantiating NodeStackClient:

import { NodeStackClient } from 'nodestack-client';

const client = new NodeStackClient('https://api.yourdomain.com', {
apiKey: process.env.NODESTACK_API_KEY, // 'nsk_live_...'
});

// Authorized operations
const order = await client.collection('orders').create({
item: 'Server Blade',
amount: 2500,
});

const products = await client.collection('products').getList(1, 10);

With Raw HTTP Requests​

Attach the key using either standard header:

Option 1: Authorization Header

curl https://api.yourdomain.com/api/collections/orders/records \
-H "Authorization: Bearer nsk_live_k8f9a2_..."

Option 2: X-API-Key Header

curl https://api.yourdomain.com/api/collections/orders/records \
-H "X-API-Key: nsk_live_k8f9a2_..."

REST API Reference​

All management endpoints require superuser (admin) authorization:

MethodEndpointDescription
GET/api/api-keysList all API keys with redacted tokens, scopes, and usage stats.
POST/api/api-keysGenerate a new API key. Full secret is returned only in this response.
GET/api/api-keys/:idRetrieve metadata for a single API key.
PATCH/api/api-keys/:idUpdate key name, scopes, IP allowlist, status, or expiration.
DELETE/api/api-keys/:idRevoke and delete an API key.
POST/api/api-keys/:id/rotateAtomically rotate the key secret.