Public API Authentication and API Keys
Create scoped NOCK API keys, authenticate requests, and understand rate limits and project access.
Public API calls require an API key created by a workspace admin. The key is shown only once when it is created, so store it in a password manager or secret store immediately. See API Keys for the workspace UI flow.
Send the API key
Use either a Bearer token:
curl -sS "https://nocknock.cloud/api/v1/projects" \
-H "Authorization: Bearer $NOCK_API_KEY"Or the x-nock-api-key header:
curl -sS "https://nocknock.cloud/api/v1/projects" \
-H "x-nock-api-key: $NOCK_API_KEY"Scopes
| Scope | Meaning |
|---|---|
tickets:read | Read project metadata, ticket lists and ticket details. |
tickets:write | Create tickets and update ticket fields. |
tickets:reply | Add customer-visible replies through Public API or MCP. |
tickets:notes:write | Add private MCP internal notes. |
webhooks:write | Manage webhooks and delivery retries. |
mcp:access | Authenticate against /mcp. |
Use the smallest scope set your integration needs. For example, an intake form
usually needs tickets:write; a reporting tool usually needs tickets:read;
an MCP reader needs mcp:access and tickets:read.
Workspace and project access
Keys can be workspace-wide or project-scoped.
| Key type | Access |
|---|---|
| Workspace key | Can access all projects in the workspace, subject to scopes. |
| Project key | Can access only the selected project, even if the request includes another project_id. |
Project-scoped keys are recommended for customer-specific automation, embedded agent workflows, and third-party vendors.
Response shape
Successful responses use:
{ "success": true, "data": {} }Errors use:
{ "success": false, "error": "Invalid or missing API key" }Rate limits
| Layer | Limit |
|---|---|
| API key | 300 requests per minute |
| IP address | 120 requests per minute |
| Pre-auth IP address | 180 requests per minute |
| Pre-auth token hash | 600 requests per minute |
Rate-limited responses return HTTP 429 with a Retry-After header.
Security recommendations
- Store keys only on servers, backend workers, or trusted automation platforms.
- Do not put API keys in browser code, public repositories, or client-side mobile apps.
- Prefer project-scoped keys for external automations.
- Rotate keys when a vendor, script, or agent no longer needs access.
- Use webhook signatures before triggering side effects in downstream systems.