Authentication Overview

SUIT supports two authentication methods for accessing the API. Both can be used interchangeably on most endpoints (Dual Auth).

Authentication methods

Method	Use case	Header format	Scope
API Key	Server-to-server integrations, automation	Authorization: Bearer sk_live_xxx	/api/* endpoints
JWT	Portal users, frontend applications	Authorization: Bearer eyJhbGc...	/api/* + /auth/* + /admin/users
Master Key	Tenant management (admin only)	Authorization: Bearer MASTER_KEY	/admin/tenants + /admin/tenants/*/api-keys

When to use each method

API Key

Use API Keys when:

• You are building a server-to-server integration
• Your backend automatically emits invoices after payments
• You need a permanent credential that does not expire
• You are setting up webhooks or automated workflows

Learn more about API Key authentication

JWT (JSON Web Token)

Use JWT when:

• You are building a user-facing application (portal, dashboard)
• You need role-based access control (admin, facturador, viewer)
• Users log in with email and password
• You need short-lived tokens for security

Learn more about JWT authentication

Authorization header format

All authenticated requests use the Authorization header with the Bearer scheme:

Authorization: Bearer YOUR_TOKEN_HERE

Where YOUR_TOKEN_HERE is either:

• Your API Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
• Your JWT access token: eyJhbGciOiJIUzI1NiIs...

Error responses

If authentication fails, the API returns HTTP 401 Unauthorized:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Common causes:

• Missing Authorization header
• Invalid or expired token
• Revoked API key
• Wrong authentication method for the endpoint