Authentication

Snipara supports multiple authentication methods: API keys for programmatic access, OAuth for interactive flows, and device flow for CLI tools.

Overview

Method	Use Case	Format
Project API Key	Single project access	`snp-...`
Service Account Key	Bot/CI project access	`snp-bot-...`
OAuth Token	Remote MCP / device flow / CLI	`snipara_at_...`

Header Formats

# API Key (recommended for scripts)

X-API-Key: snp-your_key_here

# OAuth Token (for device flow)

Authorization: Bearer snipara_at_your_token_here

Remote MCP OAuth

Remote MCP clients can discover Snipara's OAuth authorization flow directly from a protected project endpoint. Snipara supports authorization code exchange with S256 PKCE, refresh-token rotation, revocation, and dynamic client registration. Direct Client ID Metadata URLs are also accepted for compatible clients. Existing X-API-Keyconfigurations continue to work unchanged.

curl https://api.snipara.com/.well-known/oauth-protected-resource/mcp/YOUR_PROJECT_SLUG

curl https://www.snipara.com/.well-known/oauth-authorization-server

OAuth access tokens are bound to the project identified by the MCP resource URL and are sent as Authorization: Bearer snipara_at_....

API Keys

Project API Keys

Access a single project via MCP or REST API.

Access level is only one gate. The actual tool list also depends on the caller and connection surface: the default Hosted MCP manifest is intentionally lean, while Companion and Orchestrator expose additional local or coordination commands. Use snipara_help and the relevant integration guide before assuming that a tool named below is directly callable from a Hosted MCP session.

Access Level	Description	Representative Tools	Plan Requirement
VIEWER	Read-only access	`snipara_context_query`, `snipara_ask`, `snipara_search`	Core query tools are Free; semantic/hybrid and memory recall can require Pro
EDITOR	Read + Write (default)	All VIEWER + `snipara_remember`, `snipara_inject`, `snipara_upload_document`	Plan and Agents entitlement still apply per tool; memory writes are not guaranteed by EDITOR alone and may be exposed through Companion or another specialist surface.
ADMIN	Full access	All tools including `snipara_swarm_create`, `snipara_claim`, `snipara_htask_create`	Swarm coordination requires Team or Enterprise; htask tools are Orchestrator-surface capabilities and are not part of the lean default manifest

Creating API Keys

Go to Project > API Keys in dashboard
Click "Create API Key"
Enter name and select access level (VIEWER/EDITOR/ADMIN)
Copy key immediately (shown once only!)

Important: API keys are hashed before storage. The original key cannot be retrieved — copy it immediately after creation.

Using API Keys

curl -X POST https://api.snipara.com/mcp/my-project \

  -H "Content-Type: application/json" \

  -H "X-API-Key: snp-abc123..." \

  -d '{

    "jsonrpc": "2.0",

    "id": 1,

    "method": "tools/call",

    "params": {

      "name": "snipara_ask",

      "arguments": {"query": "How does auth work?"}

}'

Service Account Keys

Bot/CI keys use explicit per-project grants. Format: snp-bot-...

# Multi-project query with service account key

curl -X POST https://api.snipara.com/mcp/team/my-team \

  -H "X-API-Key: snp-bot-abc123..." \

  -d '{"jsonrpc":"2.0","method":"tools/call","params":{

    "name":"snipara_multi_project_query","arguments":{"query":"authentication"}}}'

Device Flow

Device flow lets a CLI start authorization while the user signs in and approves the request in a browser. Client profiles determine whether the exchange returns a personal user key, a project-scoped OAuth token, or an auto-provisioned project API key.

Choose the registered client profile

Use snipara-cli for the personal user-key flow. Use a registered project-scoped client such as create-snipara, snipara-mcp, orsnipara-companion for project access. Only create-snipara may create a project automatically; other project clients require the user to select an accessible project. The polling request must repeat the same client_id.

OAuth device flow

Rendering diagram...

Step 1: Request Device Code

curl -X POST https://www.snipara.com/api/oauth/device/code \

  -H "Content-Type: application/json" \

  -d '{"client_id": "create-snipara", "auto_provision": true}'

Response:

  "device_code": "abc123def456ghi789...",

  "user_code": "ABCD-1234",

  "verification_uri": "https://www.snipara.com/device",

  "verification_uri_complete": "https://www.snipara.com/device?code=ABCD-1234",

  "expires_in": 1800,

  "interval": 5

Step 2: Poll for Token

curl -X POST https://www.snipara.com/api/oauth/device/token \

  -H "Content-Type: application/json" \

  -d '{

    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",

    "device_code": "abc123def456ghi789...",

    "client_id": "create-snipara"

}'

Success response (with auto_provision: true):

  "access_token": "snipara_at_abc123...",

  "token_type": "Bearer",

  "expires_in": 86400,

  "refresh_token": "snipara_rt_def456...",

  "project_slug": "my-project",

  "api_key": "snp-abc123...",

  "mcp_endpoint": "https://api.snipara.com/mcp/my-project"

Auto-Provision

With the registered create-snipara client andauto_provision: true, an authenticated user can approve creation or reuse of a personal workspace project. The successful exchange returns its project identity and project-scoped API key. This flag is rejected for unregistered client IDs.

Personal User-Key Response

The snipara-cli profile is intentionally different. A current client sends itsclient_version while polling and receives a personal API key, not a project OAuth access/refresh pair:

  "access_token": "snp-user-...",

  "token_type": "Bearer",

  "key_type": "user",

  "user": { "id": "user_...", "email": "developer@example.com" },

  "server_url": "https://api.snipara.com"

This response has no refresh_token, expires_in, project binding, ormcp_endpoint. Resolve the target project separately when using the personal key.

Rate Limiting

Plan	Requests/Minute	Monthly Queries
FREE	30	1,000
SOLO	80	5,000
PRO	120	25,000
TEAM	300	100,000
ENTERPRISE	2,000	500,000 fair use

Rate Limit Headers

X-RateLimit-Remaining: 45

X-RateLimit-Reset: 42

Security Best Practices

Never Commit Keys

Use environment variables. Add .env to .gitignore.

Rotate Regularly

Generate new keys periodically. Revoke old keys.

Use Minimal Scope

Prefer personal or project keys for user work. Use VIEWER when write access isn't needed.

Set Expiration

Create time-limited keys for temporary access.

Environment Variables

# .env (never commit!)

SNIPARA_API_KEY=snp-your_key_here

# .gitignore

.env

.env.local

.env.*.local

Requesting Project Access

If you can authenticate but still have no effective access to a project, use snipara_request_access to ask project admins for a higher access level.

snipara_request_access

snipara_request_access({

  requested_level: "EDITOR",

  reason: "Need to upload onboarding docs and store rollout decisions"

})

This creates an access request for project admins to review in the dashboard. Use it when your identity is valid but your current role is NONE or too limited for the task you need to perform.

Troubleshooting

Error	Cause	Solution
"Missing authentication"	No credentials provided	Add `X-API-Key` header
"Invalid API key"	Key revoked or expired	Generate new key in dashboard
"Invalid OAuth token"	Project OAuth access token expired	Refresh with `refresh_token`; user-key flows return a reusable key
"Rate limit exceeded"	Too many requests	Wait and retry with backoff
"405 Method Not Allowed"	POST request sent to an endpoint that only accepts a different method	Check the route and method against the API reference before retrying

Next Steps

Getting Started

Quick setup guide for your first project.

MCP Tools

Browse the public MCP tools reference.

API Reference

REST API documentation.

Create API Key

Go to your dashboard to generate keys.