Authentication

All API endpoints (except /api/v1/health) require authentication. NeuralRepo supports two primary authentication methods and a separate MCP OAuth flow.

Session Token

When you sign in through the NeuralRepo web app, a session token is stored in a secure HTTP-only cookie. You can also pass it explicitly via the Authorization header:

Authorization: Bearer <session_token>

Session tokens are short-lived and automatically refreshed by the web client. They are best suited for browser-based integrations.

API Key

API keys provide long-lived access for scripts, CI pipelines, and third-party integrations. Every key is prefixed with nrp_ followed by 64 hexadecimal characters:

X-API-Key: nrp_a1b2c3d4e5f6...

Generating an API Key

curl

curl -X POST https://neuralrepo.com/api/v1/user/api-keys \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "CI Pipeline"}'

JavaScript

const res = await fetch("https://neuralrepo.com/api/v1/user/api-keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer <session_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ label: "CI Pipeline" }),
});
const key = await res.json();
console.log(key);

Response 201 Created

{
  "id": "ak_abc123",
  "label": "CI Pipeline",
  "key": "nrp_a1b2c3d4e5f67890...",
  "created_at": "2026-03-24T12:00:00Z"
}

Caution

The full key value is only returned once at creation time. Store it securely.

Listing Keys

GET /api/v1/user/api-keys

Returns all active keys for the authenticated user. The key field is masked.

Revoking a Key

DELETE /api/v1/user/api-keys/:id

Immediately invalidates the key. Returns 204 No Content.

Scopes

API keys support the following scopes:

Scope	Description
ideas:read	Read ideas, tags, relations, links, search, map, duplicates
ideas:write	Create, update, delete, merge, and develop ideas; manage tags, links, and relations

Session tokens have full access. API keys receive both scopes by default.

MCP OAuth

NeuralRepo provides MCP (Model Context Protocol) tokens for AI assistant integrations. The MCP OAuth flow is separate from standard API authentication:

1. Request an MCP token through the NeuralRepo dashboard or via GET /api/v1/user/mcp-tokens.
2. The MCP token is used by compatible AI clients (such as Claude) to access NeuralRepo tools.
3. MCP tokens have the same scopes as API keys.

This flow is handled automatically when you connect NeuralRepo as an MCP server in a supported client.

Error Responses

Status	Meaning
401 Unauthorized	Missing or invalid token/key
403 Forbidden	Valid auth but insufficient permissions or plan limits exceeded

{
  "error": "Invalid API key"
}

Best Practices

• Use API keys for server-side scripts and automations.
• Use session tokens only from browser-based code.
• Rotate API keys periodically and revoke unused keys.
• Never commit API keys to version control.