Authentication

Overview

SynthesQ supports two authentication mechanisms. Use the one appropriate for your integration type:

Method	Used by	Transport
Bearer token (API token)	Third-party integrations, server-to-server	`Authorization: Bearer <token>`
Session cookie (Sanctum stateful)	SPA / first-party frontend	Sanctum session cookies

Token management endpoints (/api-tokens/*) are session-authenticated - they are for your frontend to create and manage tokens, and cannot themselves be called with a Bearer token.

Quick Start

Include your API token in the Authorization header of every request:

http

GET /api/v1/operations/products HTTP/1.1
Host: api.synthesq.com
Authorization: Bearer {your-api-token}
Accept: application/json

bash

curl -X GET "https://api.synthesq.com/api/v1/operations/products" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Token is one-time visible

When you create a token, the plain-text value is returned once only in the plain_text_token field. Store it securely immediately - it cannot be retrieved again.

SPA Session Authentication

First-party SPAs authenticate using Sanctum session cookies. The flow requires a CSRF token before login and supports two-factor authentication.

Step 1 - Obtain a CSRF cookie:

http

GET /sanctum/csrf-cookie HTTP/1.1
Host: api.synthesq.com

This sets the XSRF-TOKEN cookie. Your HTTP client must include this cookie on subsequent requests.

Step 2 - Authenticate:

http

POST /api/v1/auth/login HTTP/1.1
Host: api.synthesq.com
Content-Type: application/json
X-XSRF-TOKEN: {csrf-token-from-cookie}

{
  "email": "jane@example.com",
  "password": "your-password"
}

Responses

200 - Login successful:

json

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "01hwxyz123abc456def789ghi0",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "roles": ["sales-manager"]
    }
  }
}

A session cookie is set. All subsequent requests are authenticated automatically via the cookie.

423 - Two-factor authentication required:

json

{
  "success": false,
  "message": "Two-factor authentication required"
}

If the user has two-factor authentication enabled, the login endpoint validates the credentials but does not establish a session. The SPA must prompt the user for their TOTP code and submit it to the two-factor challenge endpoint before access is granted.

Breaking change

SPA clients that previously received a 200 for 2FA-enabled users will now receive 423. Handle this response by presenting a TOTP input to the user.

401 - Invalid credentials:

json

{
  "success": false,
  "message": "Invalid credentials"
}

422 - Validation error:

json

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Logout

http

POST /api/v1/auth/logout HTTP/1.1
Host: api.synthesq.com
X-XSRF-TOKEN: {csrf-token-from-cookie}

200 - Logged out:

json

{
  "success": true,
  "message": "Logged out successfully"
}

The session is destroyed and the session cookie is invalidated.

Token Types

Three token types are available. Choose based on your use case:

Type	Value	Default Expiry	IP Whitelisting	Webhooks	Best For
Personal Access Token	`personal`	30 days	No	No	Developer testing, short-lived scripts
Application Token	`application`	365 days	No	Yes	Long-running apps, no IP restriction needed
Integration Token	`integration`	Never	Yes	Yes	Enterprise integrations requiring IP lock

Expiry behaviour: Default expiry applies when expiration_days is omitted at creation. You can override it with any value from 1 to 3650 days. Integration tokens have no default expiry and remain valid until explicitly revoked.

Token Abilities & Scopes

Format

Every ability string follows the format:

{module}:{action}

Examples: operations:view-products, crm:create-leads, finance:post-journal-entries

Available modules: system, crm, sales, operations, finance, reporting

Wildcard Patterns

Three levels of wildcard are supported, resolved by TokenPermissionMapper:

Pattern	Meaning	Example
`*`	All permissions across all modules	Full admin access
`{module}:*`	All permissions within a module	`operations:*`
`{module}:{verb}-*`	All actions with a given verb prefix	`operations:view-*`

Example: read-only operations integration

json

["operations:view-*"]

This grants access to operations:view-products, operations:view-inventory, operations:view-suppliers, and all other view-prefixed operations permissions.

Example: full CRM access

json

["crm:*"]

Example: specific abilities

json

["crm:view-leads", "crm:create-leads", "crm:edit-leads"]

Least-privilege principle

Always grant the minimum abilities needed. Avoid * except for trusted system integrations.

Permissions Reference

The tables below list every permission in the system. The ability string is what you include in a token's abilities array. Permissions with High sensitivity require tenant administrator approval before the token is activated.

Sensitivity Levels

Level	Sensitivity Score	Requires Approval
Low	10–49	No
Medium	50–79	No
High	80–100	Yes ✓

System Permissions (`system`)

Ability	Label	Sensitivity	Approval
`system:manage-system`	Manage System	High (100)	✓
`system:manage-users`	Manage Users	High (100)	✓
`system:manage-roles`	Manage Roles	High (100)	✓
`system:view-audit-logs`	View Audit Logs	Low (30)

CRM Permissions (`crm`)

Leads

Ability	Label	Sensitivity
`crm:view-leads`	View Leads	Low (25)
`crm:create-leads`	Create Leads	Low (30)
`crm:edit-leads`	Edit Leads	Low (45)
`crm:delete-leads`	Delete Leads	Medium (65)
`crm:assign-leads`	Assign Leads	Low (30)
`crm:qualify-leads`	Qualify Leads	Low (30)
`crm:convert-leads`	Convert Leads	Low (30)
`crm:score-leads`	Score Leads	Low (30)

Customers

Ability	Label	Sensitivity
`crm:view-customers`	View Customers	Low (25)
`crm:create-customers`	Create Customers	Low (30)
`crm:edit-customers`	Edit Customers	Low (45)
`crm:delete-customers`	Delete Customers	Medium (65)
`crm:manage-customer-segments`	Manage Customer Segments	Low (30)
`crm:view-customer-clv`	View Customer CLV	Low (30)

Opportunities

Ability	Label	Sensitivity
`crm:view-opportunities`	View Opportunities	Low (25)
`crm:create-opportunities`	Create Opportunities	Low (30)
`crm:edit-opportunities`	Edit Opportunities	Low (45)
`crm:delete-opportunities`	Delete Opportunities	Medium (65)
`crm:close-opportunities`	Close Opportunities	Low (30)
`crm:forecast-opportunities`	Forecast Opportunities	Low (30)

Organizations

Ability	Label	Sensitivity
`crm:view-organizations`	View Organizations	Low (30)
`crm:create-organizations`	Create Organizations	Low (30)
`crm:edit-organizations`	Edit Organizations	Low (30)
`crm:delete-organizations`	Delete Organizations	Low (30)

Contacts

Ability	Label	Sensitivity
`crm:view-contacts`	View Contacts	Low (30)
`crm:create-contacts`	Create Contacts	Low (30)
`crm:edit-contacts`	Edit Contacts	Low (30)
`crm:delete-contacts`	Delete Contacts	Low (30)

Activities

Ability	Label	Sensitivity
`crm:view-activities`	View Activities	Low (30)
`crm:create-activities`	Create Activities	Low (30)
`crm:edit-activities`	Edit Activities	Low (30)
`crm:delete-activities`	Delete Activities	Low (30)

Campaigns

Ability	Label	Sensitivity
`crm:view-campaigns`	View Campaigns	Low (30)
`crm:create-campaigns`	Create Campaigns	Low (30)
`crm:edit-campaigns`	Edit Campaigns	Low (30)
`crm:delete-campaigns`	Delete Campaigns	Low (30)
`crm:execute-campaigns`	Execute Campaigns	Low (30)

Sales Permissions (`sales`)

Orders

Ability	Label	Sensitivity	Approval
`sales:view-orders`	View Orders	Low (20)
`sales:create-orders`	Create Orders	Low (30)
`sales:edit-orders`	Edit Orders	Low (30)
`sales:delete-orders`	Delete Orders	Low (30)
`sales:cancel-orders`	Cancel Orders	Low (30)
`sales:ship-orders`	Ship Orders	Low (30)
`sales:complete-orders`	Complete Orders	Low (30)
`sales:approve-orders`	Approve Orders	High (85)	✓

Invoices

Ability	Label	Sensitivity
`sales:view-invoices`	View Invoices	Low (20)
`sales:create-invoices`	Create Invoices	Low (40)
`sales:edit-invoices`	Edit Invoices	Low (40)
`sales:delete-invoices`	Delete Invoices	Low (30)
`sales:send-invoices`	Send Invoices	Medium (50)
`sales:void-invoices`	Void Invoices	Medium (50)

Payments

Ability	Label	Sensitivity	Approval
`sales:view-payments`	View Payments	Low (30)
`sales:process-payments`	Process Payments	High (80)	✓
`sales:refund-payments`	Refund Payments	High (80)	✓
`sales:view-payment-details`	View Payment Details	High (80)	✓

Pricing

Ability	Label	Sensitivity	Approval
`sales:apply-discounts`	Apply Discounts	Low (40)
`sales:override-pricing`	Override Pricing	High (85)	✓
`sales:manage-commission`	Manage Commission	Medium (50)

Operations Permissions (`operations`)

Products

Ability	Label	Sensitivity
`operations:view-products`	View Products	Low (20)
`operations:create-products`	Create Products	Low (30)
`operations:edit-products`	Edit Products	Low (35)
`operations:delete-products`	Delete Products	Low (30)
`operations:discontinue-products`	Discontinue Products	Low (30)
`operations:manage-product-categories`	Manage Product Categories	Low (30)
`operations:manage-product-attributes`	Manage Product Attributes	Low (30)

Inventory

Ability	Label	Sensitivity
`operations:view-inventory`	View Inventory	Low (15)
`operations:manage-inventory`	Manage Inventory	Low (35)
`operations:adjust-stock`	Adjust Stock	Medium (60)
`operations:transfer-stock`	Transfer Stock	Medium (60)
`operations:reserve-stock`	Reserve Stock	Low (30)
`operations:release-stock`	Release Stock	Low (30)

Suppliers

Ability	Label	Sensitivity
`operations:view-suppliers`	View Suppliers	Low (15)
`operations:create-suppliers`	Create Suppliers	Low (30)
`operations:edit-suppliers`	Edit Suppliers	Low (35)
`operations:delete-suppliers`	Delete Suppliers	Low (30)
`operations:rate-suppliers`	Rate Suppliers	Medium (60)
`operations:manage-supplier-contracts`	Manage Supplier Contracts	Low (30)

Purchase Orders

Ability	Label	Sensitivity	Approval
`operations:view-purchase-orders`	View Purchase Orders	Low (30)
`operations:create-purchase-orders`	Create Purchase Orders	Low (30)
`operations:edit-purchase-orders`	Edit Purchase Orders	Low (30)
`operations:delete-purchase-orders`	Delete Purchase Orders	Low (30)
`operations:approve-purchase-orders`	Approve Purchase Orders	High (85)	✓
`operations:send-purchase-orders`	Send Purchase Orders	Low (30)
`operations:receive-goods`	Receive Goods	Low (30)

Coupons

Ability	Label	Sensitivity	Approval
`operations:manage-coupons`	Manage Coupons	Low (30)
`operations:apply-coupons`	Apply Coupons	Low (30)

Finance Permissions (`finance`)

Accounts

Ability	Label	Sensitivity	Approval
`finance:view-accounts`	View Accounts	Low (15)
`finance:create-accounts`	Create Accounts	Medium (55)
`finance:edit-accounts`	Edit Accounts	Medium (55)
`finance:delete-accounts`	Delete Accounts	High (90)	✓
`finance:activate-accounts`	Activate Accounts	Low (30)
`finance:deactivate-accounts`	Deactivate Accounts	Low (30)

Journal Entries

Ability	Label	Sensitivity	Approval
`finance:view-journal-entries`	View Journal Entries	Medium (55)
`finance:create-journal-entries`	Create Journal Entries	Medium (75)
`finance:edit-journal-entries`	Edit Journal Entries	Medium (75)
`finance:delete-journal-entries`	Delete Journal Entries	Low (30)
`finance:post-journal-entries`	Post Journal Entries	High (95)	✓
`finance:reverse-journal-entries`	Reverse Journal Entries	High (95)	✓

Financial Reports

Ability	Label	Sensitivity
`finance:view-financial-reports`	View Financial Reports	Medium (70)
`finance:generate-financial-reports`	Generate Financial Reports	Low (30)
`finance:export-financial-data`	Export Financial Data	Medium (70)

Budgets, Expenses & Configuration

Ability	Label	Sensitivity	Approval
`finance:manage-budgets`	Manage Budgets	Medium (75)
`finance:approve-expenses`	Approve Expenses	High (90)	✓
`finance:reconcile-accounts`	Reconcile Accounts	High (90)	✓
`finance:view-sensitive-financial-data`	View Sensitive Financial Data	High (95)	✓
`finance:manage-tax-configuration`	Manage Tax Configuration	High (95)	✓

Reporting Permissions (`reporting`)

Ability	Label	Sensitivity
`reporting:view-reports`	View Reports	Low (10)
`reporting:create-reports`	Create Reports	Low (30)
`reporting:share-reports`	Share Reports	Low (30)
`reporting:export-data`	Export Data	Low (30)
`reporting:view-analytics`	View Analytics	Low (10)
`reporting:view-dashboard`	View Dashboard	Low (10)

Roles Reference

Roles define what a user can do within the system. They are assigned by tenant administrators and determine which API abilities can be granted to tokens the user creates.

Hierarchy

Role	Label	Level	Module Scope	Approval Limit
`super-admin`	Super Administrator	100	All modules	$1,000,000
`system-admin`	System Administrator	95	-	$5,000
`crm-admin`	CRM Administrator	90	crm	$5,000
`sales-admin`	Sales Administrator	90	sales	$100,000
`operations-admin`	Operations Administrator	90	operations	$500,000
`finance-admin`	Finance Administrator	90	finance	$500,000
`crm-manager`	CRM Manager	80	crm	$5,000
`sales-manager`	Sales Manager	80	sales	$100,000
`operations-manager`	Operations Manager	80	operations	$250,000
`finance-manager`	Finance Manager	80	finance	$250,000
`reporting-analyst`	Reporting Analyst	75	-	$5,000
`sales-representative`	Sales Representative	72	sales	$5,000
`account-manager`	Account Manager	72	sales	$5,000
`customer-support`	Customer Support Specialist	72	crm	$5,000
`senior-accountant`	Senior Accountant	70	finance	$50,000
`sales-rep`	Sales Representative	70	sales	$25,000
`accountant`	Accountant	70	finance	$25,000
`procurement-specialist`	Procurement Specialist	70	operations	$50,000
`customer-service`	Customer Service Representative	60	crm	$5,000
`inventory-clerk`	Inventory Clerk	60	operations	$10,000
`junior-sales-rep`	Junior Sales Representative	50	sales	$5,000
`junior-accountant`	Junior Accountant	50	finance	$5,000
`data-entry-clerk`	Data Entry Clerk	40	-	$5,000

Approval limit is the maximum financial transaction value the role can approve without escalation.

Module scope determines which modules the role can manage. super-admin manages all modules.

Default Permissions by Role

Role	Default Permission Set
`super-admin`	All permissions
`crm-admin`	All `crm:` + all `reporting:`
`sales-admin`	All `sales:` + all `crm:` + all `reporting:*`
`operations-admin`	All `operations:` + all `reporting:`
`finance-admin`	All `finance:` + all `reporting:`

Rate Limiting

All API token requests are subject to rate limiting based on the token's tier.

Tiers

Tier	Value	Requests per Minute	Burst Allowed
Basic	`basic`	60	No
Standard	`standard`	300	Yes
Premium	`premium`	600	Yes
Unlimited	`unlimited`	999,999	Yes

Set the tier when creating a token via the rate_limit_tier field. If omitted, the system assigns a default tier.

Response Headers

Every API response includes rate limit headers:

Header	Present when	Description
`X-RateLimit-Limit`	Always	Maximum requests per minute for this token
`X-RateLimit-Remaining`	Always	Remaining requests in the current window
`Retry-After`	On `429` only	Seconds until the window resets
`X-RateLimit-Reset`	On `429` only	Unix timestamp when the window resets

429 Too Many Requests

json

{
  "message": "Too many requests. Please try again later."
}

Headers on 429:

http

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 45
X-RateLimit-Reset: 1737028245

Token Management

Token management endpoints are session-authenticated (SPA / first-party frontend only). They are not accessible via Bearer token. Authenticate your frontend via Sanctum stateful sessions before calling these endpoints.

Endpoints

Method	Path	Description
`GET`	`/api-tokens`	List all tokens for the authenticated user
`POST`	`/api-tokens`	Create a new API token
`GET`	`/api-tokens/{id}`	Get a specific token's details
`DELETE`	`/api-tokens/{id}`	Delete a token permanently
`POST`	`/api-tokens/{id}/revoke`	Revoke a token (soft-disable, keeps audit trail)
`POST`	`/api-tokens/{id}/rotate`	Rotate token - invalidates old, issues new
`GET`	`/api-tokens/{id}/usage`	Get token usage statistics

Create Token - `POST /api-tokens`

Request body:

json

{
  "name": "My Integration",
  "token_type": "integration",
  "abilities": ["operations:view-products", "operations:view-inventory"],
  "description": "Read-only access for ERP sync",
  "rate_limit_tier": "standard",
  "expiration_days": null,
  "allowed_ips": ["203.0.113.10", "203.0.113.11"],
  "webhook_url": "https://my-app.example.com/webhooks/crm"
}

Field	Type	Required	Description
`name`	string	Yes	Human-readable token name (max 255 chars)
`token_type`	string	Yes	`personal`, `application`, or `integration`
`abilities`	array	Yes	Ability strings the token can use
`description`	string	No	Optional description (max 500 chars)
`rate_limit_tier`	string	No	`basic`, `standard`, `premium`, or `unlimited`
`expiration_days`	integer\|null	No	Days until expiry (1–3650). `null` = no expiry
`allowed_ips`	array\|null	No	IP whitelist - `integration` tokens only
`webhook_url`	string\|null	No	Webhook URL - `application` and `integration` tokens only

Response 201 Created:

json

{
  "success": true,
  "message": "API token created successfully",
  "data": {
    "id": "01hwxyz123abc456def789ghn0",
    "name": "My Integration",
    "description": "Read-only access for ERP sync",
    "token_type": "integration",
    "token_type_label": "Integration Token",
    "abilities": ["operations:view-products", "operations:view-inventory"],
    "rate_limit": {
      "tier": "standard",
      "tier_label": "Standard (300/min)",
      "requests_per_minute": 300
    },
    "usage": {
      "request_count": 0,
      "first_used_at": null,
      "last_used_at": null
    },
    "security": {
      "allowed_ips": ["203.0.113.10", "203.0.113.11"],
      "has_ip_restriction": true,
      "webhook_url": "https://my-app.example.com/webhooks/crm"
    },
    "status": {
      "is_active": true,
      "is_expired": false,
      "is_revoked": false,
      "revoked_at": null,
      "revoked_by": null,
      "revocation_reason": null
    },
    "rotation": {
      "rotated_at": null,
      "rotated_from_token_id": null
    },
    "expires_at": null,
    "created_at": "2026-01-15T10:30:00+00:00",
    "updated_at": "2026-01-15T10:30:00+00:00"
  },
  "plain_text_token": "1|abcdef1234567890..."
}

One-time token visibility

plain_text_token is only returned once at creation time. It cannot be retrieved again. Copy and store it securely before closing the response.

Advanced Features

IP Whitelisting

integration tokens support an allowed_ips array. When set, every request using that token is checked against the list by the CheckTokenIpWhitelist middleware.

Requests from IPs not in the list are rejected immediately with 403 Forbidden:

json

{ "message": "Access denied. Your IP address is not whitelisted for this token." }

Requests from whitelisted IPs proceed normally.
personal and application tokens do not support IP whitelisting.

Example: restricting to your office and CI/CD IP ranges

json

{
  "token_type": "integration",
  "allowed_ips": ["203.0.113.10", "203.0.113.20", "198.51.100.0"]
}

Webhooks

application and integration tokens accept an optional webhook_url. The system dispatches webhook events asynchronously via SendTokenWebhookJob when token lifecycle events occur:

Event	Trigger
`token.created`	A new token is created
`token.rotated`	A token is rotated (old invalidated, new issued)
`token.revoked`	A token is revoked

Webhook payload:

json

{
  "event": "token.created",
  "timestamp": "2026-01-15T10:30:00+00:00",
  "data": { }
}

Webhook headers:

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Event`	The event name (e.g. `token.created`)
`X-Webhook-Signature`	HMAC-SHA256 signature of the payload body

Verifying the signature:

The signature is computed as HMAC-SHA256(json_encode(payload), webhook_secret). Verify it on your receiver to ensure authenticity. The webhook secret is configured by your tenant administrator.

Webhook delivery is attempted up to 3 times with a 60-second backoff between retries. Delivery times out after 10 seconds per attempt.

Token Rotation

POST /api-tokens/{id}/rotate invalidates the current token and issues a replacement with the same abilities and configuration. The response includes a new plain_text_token - store it immediately.

The original token's rotation.rotated_at and new token's rotation.rotated_from_token_id fields track the rotation chain for audit purposes.

Use rotation to refresh long-lived tokens periodically without disrupting integrations.

Sensitive Permissions & Approval

The following permissions have a sensitivity level ≥ 80 and require tenant administrator approval before a token requesting them is activated:

System

system:manage-system, system:manage-users, system:manage-roles

Sales

sales:approve-orders, sales:override-pricing
sales:process-payments, sales:refund-payments, sales:view-payment-details

Operations

operations:approve-purchase-orders

Finance

finance:delete-accounts, finance:approve-expenses, finance:reconcile-accounts
finance:post-journal-entries, finance:reverse-journal-entries
finance:view-sensitive-financial-data, finance:manage-tax-configuration

Contact your tenant administrator if a token you created with these abilities is not yet active.

Security Best Practices

Token Storage

Never store tokens in source code or version control
Use encrypted secrets management (HashiCorp Vault, AWS Secrets Manager, environment variables)
Use separate tokens for each integration - never share tokens between systems
Use integration token type with IP whitelisting for production enterprise integrations

Token Lifecycle

Grant the minimum abilities needed for each integration (least-privilege)
Set explicit expiration_days for tokens used in scripts or temporary workflows
Rotate tokens periodically with POST /api-tokens/{id}/rotate
Revoke tokens immediately when an integration is retired or a secret is compromised

Token Transmission

Always use HTTPS - never send tokens over unencrypted connections
Pass tokens via the Authorization: Bearer header only - never in URL query parameters
Exclude tokens from application logs and error reporting

Error Reference

401 Unauthorized

Token is missing, malformed, expired, or the Sanctum session has ended.

json

{ "message": "Unauthenticated" }

Resolution: Check that the Authorization: Bearer {token} header is present and the token has not expired. If expired, create a new token via the SPA.

403 Forbidden

Token is valid but lacks the required ability for the endpoint, or the client IP is not whitelisted.

Insufficient abilities:

json

{
  "message": "Insufficient token abilities",
  "required": ["operations:create-products"],
  "token_abilities": ["operations:view-products"]
}

IP not whitelisted (integration tokens):

json

{ "message": "Access denied. Your IP address is not whitelisted for this token." }

Resolution: Verify the token's abilities include what the endpoint requires, or contact your administrator to update the token. For IP errors, ensure the request originates from a whitelisted address.

423 Locked (Two-Factor Required)

The user's credentials are valid but two-factor authentication must be completed before a session is granted. This applies to both the SPA login endpoint and the Gateway auth proxy.

json

{ "success": false, "message": "Two-factor authentication required" }

Resolution: Prompt the user for their TOTP code and submit it to the two-factor challenge endpoint.

429 Too Many Requests

Rate limit exceeded for this token.

json

{ "message": "Too many requests. Please try again later." }

Inspect the Retry-After header for the number of seconds to wait before retrying.

Tenant Management - Landlord tenant management and superuser invitations
API Reference - Per-endpoint authentication requirements
Error Handling - Full error response reference

Authentication ​

Overview ​

Quick Start ​

SPA Session Authentication ​

Login Flow ​

Responses ​

Logout ​

Token Types ​

Token Abilities & Scopes ​

Format ​

Wildcard Patterns ​

Permissions Reference ​

Sensitivity Levels ​

System Permissions (system) ​

CRM Permissions (crm) ​

Sales Permissions (sales) ​

Operations Permissions (operations) ​

Finance Permissions (finance) ​

Reporting Permissions (reporting) ​

Roles Reference ​

Hierarchy ​

Default Permissions by Role ​

Rate Limiting ​

Tiers ​

Response Headers ​

429 Too Many Requests ​

Token Management ​

Endpoints ​

Create Token - POST /api-tokens ​

Advanced Features ​

IP Whitelisting ​

Webhooks ​

Token Rotation ​

Sensitive Permissions & Approval ​

Security Best Practices ​

Token Storage ​

Token Lifecycle ​

Token Transmission ​

Error Reference ​

401 Unauthorized ​

403 Forbidden ​

423 Locked (Two-Factor Required) ​

429 Too Many Requests ​

Related Resources ​

Authentication

Overview

Quick Start

SPA Session Authentication

Login Flow

Responses

Logout

Token Types

Token Abilities & Scopes

Format

Wildcard Patterns

Permissions Reference

Sensitivity Levels

System Permissions (`system`)

CRM Permissions (`crm`)

Sales Permissions (`sales`)

Operations Permissions (`operations`)

Finance Permissions (`finance`)

Reporting Permissions (`reporting`)

Roles Reference

Hierarchy

Default Permissions by Role

Rate Limiting

Tiers

Response Headers

429 Too Many Requests

Token Management

Endpoints

Create Token - `POST /api-tokens`

Advanced Features

IP Whitelisting

Webhooks

Token Rotation

Sensitive Permissions & Approval

Security Best Practices

Token Storage

Token Lifecycle

Token Transmission

Error Reference

401 Unauthorized

403 Forbidden

423 Locked (Two-Factor Required)

429 Too Many Requests

Related Resources