🏴‍☠️ CaptainBook Auth — API Docs

← Back to Admin

Overview

Central authentication & authorization service for CaptainBook internal tools. Manages users, permissions, and API keys.

Base URL: https://auth.ops.withcaptainbook.com

Authentication

All protected endpoints accept one of:

Authorization: Bearer <jwt_or_api_key>

Public Endpoints

POST /api/login

Session-based login (sets cookie).

{
  "email": "user@captainbook.io",
  "password": "secret"
}

Returns: { "ok": true, "user": { "id", "name", "email", "role" } }

POST /api/token

Get a JWT token (for programmatic access).

{
  "email": "user@captainbook.io",
  "password": "secret"
}

Returns: { "token": "eyJ...", "user": { ... } } — token valid for 7 days.

POST /api/logout

Clear session cookie.

Token Validation (for other tools)

This is the key endpoint your other tools should call to validate users and check permissions.

POST /api/validate

Validate a token/API key and optionally check tool-level permission.

// Headers
Authorization: Bearer <user_token_or_api_key>

// Body (optional)
{ "tool": "dealroom" }

Returns:

// Without tool check
{ "valid": true, "user": { "id": 1, "email": "...", "name": "...", "role": "viewer" } }

// With tool check
{ "valid": true, "user": { ... }, "permission": "read" }

// No access
{ "valid": true, "user": { ... }, "permission": null, "error": "No access to this tool" }

// Admin users always get permission: "admin"

Integration Example

Add this middleware to any tool:

async function checkAuth(req, res, next) {
  const token = req.headers.authorization;
  if (!token) return res.status(401).json({ error: 'No token' });

  const resp = await fetch('https://auth.ops.withcaptainbook.com/api/validate', {
    method: 'POST',
    headers: { 'Authorization': token, 'Content-Type': 'application/json' },
    body: JSON.stringify({ tool: 'my-tool-slug' })
  });
  const data = await resp.json();

  if (!data.valid) return res.status(401).json({ error: 'Invalid token' });
  if (!data.permission) return res.status(403).json({ error: 'No access' });

  req.user = data.user;
  req.permission = data.permission;  // 'read', 'write', or 'admin'
  next();
}

User Management (admin only)

GET /api/users

List all users.

POST /api/users

Create a user.

{
  "email": "investor@example.com",
  "name": "John Doe",
  "password": "secure123",
  "role": "viewer"    // "admin" or "viewer"
}

PUT /api/users/:id

Update user (name, email, role, status, password).

DELETE /api/users/:id

Delete a user and all their permissions/keys.

Tools Registry

GET /api/tools

List registered tools.

POST /api/tools

Register a new tool.

{ "slug": "analytics", "name": "Analytics Dashboard", "url": "https://analytics.ops.withcaptainbook.com" }

DELETE /api/tools/:slug

Remove a tool (also deletes its permissions).

Permissions

GET /api/permissions

List all permissions (admin only).

PUT /api/permissions

Grant or update a permission.

{
  "user_id": 2,
  "tool_slug": "dealroom",
  "level": "read"       // "read", "write", or "admin"
}

DELETE /api/permissions/:id

Revoke a permission.

API Keys

GET /api/keys

List your API keys (admins can pass ?user_id=N).

POST /api/keys

Create a new API key.

{ "name": "ci-deploy", "user_id": 1 }

Returns the full key once — save it immediately:

{ "ok": true, "key": "cb_a1b2c3...", "prefix": "cb_a1b2c3...", "warning": "Save this key now" }

DELETE /api/keys/:id

Revoke an API key.

Account

GET /api/me

Get current user info and permissions.

PUT /api/me/password

Change your password.

{
  "current_password": "old-pass",
  "new_password": "new-secure-pass"
}

Roles

Permission Levels