Projects, keys and sessions
Project management runs with the admin key (ADMIN_API_KEY) or a dashboard session. Project keys can't reach these routes, and they aren't rate-limited.
Create a project
POST/v1/projects
Auth: Admin key or a dashboard session. Project keys are rejected.
Creates a project and its first key, with the admin role. The key is returned once.
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes |
Responses
{
"id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"apiKey": "nk_live_3f9c2a7e1b5d8f04c6a9e2b7d1f3c5a8e0b4d6f2a9c1e7b3d5f8a0c2e4b6d9f1"
}
{
"error": "validation_error",
"issues": [
{
"expected": "string",
"code": "invalid_type",
"path": [
"name"
],
"message": "Invalid input: expected string, received undefined"
}
]
}
Common errors (401, 403, 400, 413, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "forbidden",
"message": "Session is read-only"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/projects \
-H "Authorization: Bearer $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "production" }'
List projects
GET/v1/projects
Auth: Admin key or a dashboard session. Project keys are rejected.
Newest first. null limits use the server defaults.
Responses
{
"projects": [
{
"id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "staging",
"rateLimitRpm": 6000,
"throttleLimit": 0,
"throttleWindowHours": 1,
"createdAt": "2026-11-01T09:00:00.000Z"
},
{
"id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "production",
"rateLimitRpm": null,
"throttleLimit": null,
"throttleWindowHours": null,
"createdAt": "2026-10-02T08:30:00.000Z"
}
]
}
{
"projects": []
}
Common errors (401, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/projects -H "Authorization: Bearer $ADMIN_API_KEY"
const { projects } = await admin.listProjects();
admin is a NotifkitClient created with the admin key.
Update project limits
PATCH/v1/projects/{id}
Auth: Admin key or a dashboard session. Project keys are rejected.
Applies on the next request or notification. null restores the default. Send at least one field.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Project id. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
rateLimitRpm | number or null | no | API requests per minute. Default 600. |
throttleLimit | number or null | no | Messages per user per window. Default RATE_LIMIT_PER_HOUR (100). 0 stops every non-critical send. |
throttleWindowHours | number or null | no | Window length. Default 1. |
Responses
{
"id": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
{
"error": "validation_error",
"issues": [
{
"path": "rateLimitRpm",
"message": "Invalid input: expected number, received string"
}
]
}
{
"error": "project_not_found"
}
{
"error": "internal_error"
}
Common errors (401, 403, 400, 413, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "forbidden",
"message": "Session is read-only"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X PATCH http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "rateLimitRpm": 6000 }'
await admin.updateProject(projectId, { rateLimitRpm: 6000 });
Delete a project
DELETE/v1/projects/{id}
Auth: Admin key or a dashboard session. Project keys are rejected.
Deletes the project with its users, contacts, suppressions, delivery log and workflows. It can't be undone.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Project id. |
Responses
No body.
{
"error": "project_not_found"
}
Common errors (401, 403, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "forbidden",
"message": "Session is read-only"
}
{
"error": "internal_error"
}
Example
curl -X DELETE http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d -H "Authorization: Bearer $ADMIN_API_KEY"
await admin.deleteProject(projectId);
Create an API key
POST/v1/projects/{id}/keys
Auth: Admin key or a dashboard session. Project keys are rejected.
The key is returned once. Use read_only for dashboards and reporting. A missing or unknown role creates an admin key rather than failing.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Project id. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
role | string | no | admin (default) or read_only. |
Responses
{
"id": "8d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"apiKey": "nk_live_a71b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b",
"role": "read_only"
}
{
"error": "project_not_found"
}
Common errors (401, 403, 400, 413, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "forbidden",
"message": "Session is read-only"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys \
-H "Authorization: Bearer $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "role": "read_only" }'
const { apiKey } = await admin.createProjectKey(projectId, { role: "read_only" });
List API keys
GET/v1/projects/{id}/keys
Auth: Admin key or a dashboard session. Project keys are rejected.
Ids and roles only, newest first. Secrets are never returned again. An unknown project returns an empty list.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Project id. |
Responses
{
"keys": [
{
"id": "8d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"role": "read_only",
"createdAt": "2026-11-17T09:12:00.000Z"
},
{
"id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"role": "admin",
"createdAt": "2026-10-02T08:30:00.000Z"
}
]
}
{
"error": "project_not_found"
}
Common errors (401, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys -H "Authorization: Bearer $ADMIN_API_KEY"
const { keys } = await admin.listProjectKeys(projectId);
Revoke an API key
DELETE/v1/projects/{id}/keys/{keyId}
Auth: Admin key or a dashboard session. Project keys are rejected.
Takes effect immediately on every API process.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Project id. |
keyId | string | Key id. |
Responses
No body.
{
"error": "key_not_found"
}
Common errors (401, 403, 500)
{
"error": "unauthorized",
"message": "Missing admin token"
}
{
"error": "unauthorized",
"message": "Invalid admin token"
}
{
"error": "forbidden",
"message": "Session is read-only"
}
{
"error": "internal_error"
}
Example
curl -X DELETE http://localhost:3000/v1/projects/b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d/keys/KEY_ID -H "Authorization: Bearer $ADMIN_API_KEY"
await admin.deleteProjectKey(projectId, keyId);
Dashboard sessions
The dashboard logs in with these. Users come from ADMIN_EMAIL and ADMIN_PASSWORD. A session token works like the admin key for 7 days.
Log in
POST/v1/auth/login
Auth: None.
Body
| Field | Type | Required | Description |
|---|---|---|---|
identifier | string | yes | Email or username. |
password | string | yes |
Responses
{
"token": "nk_sess_9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d",
"user": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "[email protected]",
"username": "you",
"role": "superadmin"
},
"expiresAt": 1732442400000
}
{
"error": "validation_error",
"issues": [
{
"path": "identifier",
"message": "Identifier (email or username) is required"
},
{
"path": "password",
"message": "Password is required"
}
]
}
{
"error": "unauthorized",
"message": "Invalid credentials"
}
{
"error": "too_many_requests",
"message": "Too many login attempts. Please try again later."
}
Common errors (400, 413, 500)
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "identifier": "[email protected]", "password": "…" }'
Current session
GET/v1/auth/me
Auth: A dashboard session token.
Responses
{
"user": {
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"email": "[email protected]",
"username": "you",
"role": "superadmin"
}
}
{
"error": "unauthorized",
"message": "Invalid or expired session"
}
{
"error": "unauthorized",
"message": "Missing token"
}
Common errors (401, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/auth/me -H "Authorization: Bearer $SESSION"
Log out
POST/v1/auth/logout
Auth: A dashboard session token.
Ends the session in the header. Allowed for read-only sessions.
Responses
200 OK Logged out, or there was no session to end.
{
"message": "Logged out successfully"
}
Common errors (401, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/auth/logout -H "Authorization: Bearer $SESSION"