Nichify Agent Authentication

Step-by-step guide for AI agents and server-to-server clients to authenticate with the Nichify API and MCP server using Personal Access Tokens. If you're an AI agent, follow these exactly - no browser, no cookies, no OAuth dance.

TL;DR

A human user signs in at https://nichify.app/account/keys and clicks "Create new key".
They copy the resulting token (shown once, starts with nch_), paste it into your agent's secret store.
Your agent sends Authorization: Bearer nch_... on every request to /api/* (REST) or /mcp (MCP).
Cookies, CSRF tokens, and the session_token cookie are not used for agent traffic.

Authentication model

Caller	Credential	Header / storage
Human (browser)	Email+password or Google OAuth	Cookie `session_token`, `HttpOnly`, `Secure`, `SameSite=Lax`
AI agent / CLI / server	Personal Access Token (PAT)	`Authorization: Bearer nch_...`
Stripe webhook	Stripe-Signature header	HMAC SHA-256 verified server-side

Step-by-step: getting and using a PAT

Step 1 - Create a Nichify account (one-time, human action) Sign up at /auth?intent=register. No credit card required for the 7-day trial. Agents cannot self-register.

Step 2 - Open the PAT manager Once signed in, visit /account/keys. This page requires the browser session; it's human-only by design.

Step 3 - Create a new key Click "Create new key", label it (e.g. "claude-desktop", "zapier-bot"), pick the scopes you need (read for list/get/export, write for create analyses/monitors). The plaintext token is shown once - copy it immediately into your agent's secret store.

Step 4 - Send the token on every request Set Authorization: Bearer nch_.... Works the same for REST and MCP:

# REST
curl -H "Authorization: Bearer nch_abcdef..." \
  https://nichify.app/api/analyses

# MCP (JSON-RPC over Streamable HTTP)
curl -X POST https://nichify.app/mcp \
  -H "Authorization: Bearer nch_abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Step 5 - Handle auth failures If the token is missing, malformed, expired, or revoked, Nichify returns 401 Unauthorized with RFC-7807 problem+json:

{
  "error": {
    "code": "unauthorized",
    "message": "Not authenticated",
    "docs_url": "/account/keys",
    "suggest": [
      "Issue a PAT at /account/keys",
      "Send Authorization: Bearer nch_..."
    ]
  }
}

Branch your retry logic on error.code, not on the human message.

Step 6 - Rotate on a schedule PATs don't auto-expire, but we recommend rotating every 90 days. Create a new key first, switch your agent to it, then revoke the old key from /account/keys. Revocation is effective immediately.

Scopes

Scope	What it grants	Tools / endpoints
`read`	List, get, export	`list_analyses`, `get_analysis`, `list_monitorings`, `list_runs`, all GET `/api/*`
`write`	Create, update, delete	`create_monitor`, `create_analysis`, POST/PUT/DELETE `/api/*`

A PAT can carry both scopes. Omit write if your agent only reads.

What NOT to do

Never commit PATs to source control. Use an environment variable, a secret manager (AWS Secrets Manager, Doppler, 1Password, GitHub Actions secrets), or your platform's credential vault.

Never share one PAT across agents. Each bot/CLI/integration gets its own PAT. Revocation then affects only that one caller.

Never log the PAT. Nichify itself does not log PATs; your own observability stack must redact Authorization headers.

MCP-specific notes

The MCP server at /mcp uses the same PAT. Discovery (manifest, server card, JSON-RPC initialize and tools/list at /.well-known/mcp/manifest.json) works without auth so scanners can enumerate tools. tools/call requires a PAT.

For Claude Desktop: add an entry to claude_desktop_config.json:

{
  "mcpServers": {
    "nichify": {
      "url": "https://nichify.app/mcp",
      "headers": {
        "Authorization": "Bearer nch_your_token_here"
      }
    }
  }
}

Rate limits

300 requests/minute per IP on /mcp. REST endpoints inherit per-plan quotas (see /pricing.md). On 429, the response includes retry_after_seconds and a Retry-After header.