Authentication
Secure your API requests with organization-scoped API keys.
API Key Authentication
NookHive uses API keys to authenticate requests. Each organization can create multiple API keys with specific permission scopes. API keys provide access to your organization's resources, so keep them secure.
All API requests must be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will return a 401 Unauthorized error.
Authentication Flow
The complete authentication flow for making API requests:
Obtain API Key
Create an API key from Organization Settings → API Keys
Include in Authorization Header
Add Authorization: Bearer nk_live_... to every request
Server Validates Key
NookHive validates the key and checks organization permissions
Request Processed
API returns organization-scoped data based on the key's permissions
🔑 Creating API Keys
API keys are created from your organization profile page in the NookHive dashboard:
- Navigate to Organization Settings in the dashboard
- Select the API Keys tab
- Click "Create New Key"
- Give your key a descriptive name (e.g., "Production Server", "CI/CD Pipeline")
- Copy the key immediately—it will only be shown once
Organization-Scoped Access
Each API key is bound to a single organization. When you make an API request, you can only access resources that belong to the organization associated with your key.
What This Means:
- Events, bookings, and members returned are filtered to your organization
- You cannot access resources from other organizations
- API keys inherit the permissions of the organization admin who created them
- Rate limits are applied per organization, not per key
# This request only returns events from the organization
# associated with your API key
curl -X GET "https://api.nookhive.com/v1/events" \
-H "Authorization: Bearer nk_live_abc123..."Using Your API Key
Include your API key in the Authorization header of every request using the Bearer token format:
Authorization: Bearer nk_live_your_api_key_hereExample Requests
cURL
curl -X GET "https://api.nookhive.com/v1/events" \
-H "Authorization: Bearer nk_live_your_api_key_here" \
-H "Content-Type: application/json"JavaScript (fetch)
const response = await fetch('https://api.nookhive.com/v1/events', {
method: 'GET',
headers: {
'Authorization': 'Bearer nk_live_your_api_key_here',
'Content-Type': 'application/json'
}
});
const data = await response.json();
console.log(data);TypeScript (with type safety)
interface Event {
id: string;
slug: string;
title: string;
startDate: string;
status: 'DRAFT' | 'PUBLISHED' | 'CANCELLED';
}
interface EventsResponse {
events: Event[];
total: number;
page: number;
limit: number;
}
async function getEvents(): Promise<EventsResponse> {
const response = await fetch('https://api.nookhive.com/v1/events', {
headers: {
'Authorization': `Bearer ${process.env.NOOKHIVE_API_KEY}`,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
return response.json();
}Response Example
A successful authenticated request returns your organization's data:
{
"events": [
{
"id": "evt_example123",
"slug": "annual-conference-2026",
"title": "Annual Conference 2026",
"startDate": "2026-03-15T09:00:00Z",
"endDate": "2026-03-15T18:00:00Z",
"status": "PUBLISHED",
"createdAt": "2026-01-10T08:00:00Z",
"updatedAt": "2026-01-15T14:30:00Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}API Key Format
NookHive API keys follow a predictable format to help you identify them:
| Environment | Prefix | Example |
|---|---|---|
| Production | nk_live_ | nk_live_abc123def456ghi789... |
| Test/Sandbox | nk_test_ | nk_test_abc123def456ghi789... |
Key Structure
nk_<environment>_<32 alphanumeric characters>Total length: 40 characters (prefix + 32 random chars)
Security Best Practices
✅ Do
- Store keys in environment variables
Use
NOOKHIVE_API_KEYor similar in your .env file - Rotate production keys every 90 days
Regular rotation limits exposure from compromised keys
- Use separate keys for each environment
Never use production keys in development or testing
- Restrict access on a need-to-know basis
Only share keys with team members who need them
- Monitor API key usage for anomalies
Set up alerts for unusual request patterns
❌ Don't
- Commit keys to version control
Add .env to .gitignore; use secrets management for CI/CD
- Share keys in support tickets or chat
If a key is exposed, revoke it immediately and create a new one
- Expose keys in client-side JavaScript
API calls should be made from your backend server
- Use production keys in development
Use test keys (nk_test_) for local development
- Include keys in URLs or query parameters
URLs are logged; always use the Authorization header
Authentication Errors
When authentication fails, you'll receive one of these error responses:
401 Unauthorized - Missing API Key
The request did not include an Authorization header.
{
"error": {
"code": "UNAUTHORIZED",
"message": "API key is required. Include it in the Authorization header."
}
}401 Unauthorized - Invalid API Key
The provided API key is not valid or has been revoked.
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid or has been revoked."
}
}401 Unauthorized - Expired API Key
The API key has expired and needs to be rotated.
{
"error": {
"code": "API_KEY_EXPIRED",
"message": "Your API key has expired. Please create a new key."
}
}403 Forbidden - Insufficient Permissions
The API key is valid but doesn't have permission for this action.
{
"error": {
"code": "FORBIDDEN",
"message": "Your API key does not have permission to perform this action.",
"details": {
"requiredPermission": "events:write",
"currentPermissions": ["events:read", "members:read"]
}
}
}IP Allowlisting (Enterprise)
Enterprise customers can restrict API key usage to specific IP addresses or CIDR ranges. This adds an additional layer of security by ensuring requests can only come from trusted sources.
Example Configuration
{
"allowedIPs": [
"203.0.113.0/24",
"198.51.100.42"
],
"restrictionMode": "STRICT"
}Contact your account manager or email enterprise@nookhive.com to configure IP allowlisting for your organization.