Authentication

Overview

Cotizera uses session-based authentication powered by NextAuth with the Credentials provider. After authenticating, a JWT session cookie is issued that must be included in all subsequent API requests.

Obtaining a Session

Send a POST request to the NextAuth credentials endpoint:

curl -X POST https://cotizera.com/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}' \
  -c cookies.txt

On success, the response sets a next-auth.session-token cookie. Save this cookie and include it in subsequent requests.

Making Authenticated Requests

Include the session cookie with every API call:

curl https://cotizera.com/api/quotes \
  -b cookies.txt

Session Shape

The session includes the following fields:

Field	Type	Description
`user.id`	`string`	User ID
`user.email`	`string`	User email
`user.name`	`string`	Display name
`user.role`	`string`	`OWNER` or `COLLABORATOR`
`user.tenantId`	`string`	Tenant (business) ID
`user.plan`	`string`	`FREE` or `PRO`

Role-Based Access Control (RBAC)

Every API endpoint checks the user's role before allowing access. The permission matrix below shows what each role can do.

Permission Matrix

Permission	OWNER	COLLABORATOR
`quotes:create`	✅	✅
`quotes:read`	✅	✅
`quotes:read_all`	✅	❌
`products:manage`	✅	❌
`products:read`	✅	✅
`products:create`	✅	❌
`products:update`	✅	❌
`products:delete`	✅	❌
`clients:manage`	✅	❌
`clients:read`	✅	✅
`clients:create`	✅	✅
`clients:update`	✅	❌
`clients:delete`	✅	❌
`config:manage`	✅	❌
`pipeline:view`	✅	❌
`dashboard:view`	✅	❌
`collaborators:manage`	✅	❌

Key Notes

COLLABORATOR has limited access: create quotes, read products, read/create clients
OWNER has full tenant access including settings, pipeline, dashboard, and team management
Collaborators can only see their own quotes (quotes:read), while Owners can see all quotes (quotes:read_all)

Plan-Gated Features

Some features require the PRO plan. Attempting to access a plan-gated feature on the FREE plan returns a 403 error.

Feature	FREE	PRO
Webhooks	❌	✅
Pipeline	❌	✅
Dashboard	❌	✅
Collaborators	❌	✅
Digital Signatures	❌	✅
Quote Versioning	❌	✅
Multi-Currency	❌	✅
Audit Log UI	❌	✅
Client Portal	❌	✅
PDF Branding	❌	✅

Example: Full Authentication Flow

# 1. Login and save the session cookie
curl -X POST https://cotizera.com/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@mybusiness.com", "password": "s3cret"}' \
  -c cookies.txt
 
# 2. List your quotes
curl https://cotizera.com/api/quotes \
  -b cookies.txt
 
# 3. Create a new client
curl -X POST https://cotizera.com/api/clients \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name": "Acme Corp", "email": "contact@acme.com"}'

Error Responses

Status	Meaning
`401`	Not authenticated — session cookie missing or expired
`403`	Insufficient permissions — role or plan check failed

See the Errors guide for the full list of error codes.

PreviousIntroduction NextErrors