Authentication

This guide explains how to authenticate with the Mandaitor API, manage your API keys, and follow security best practices for production deployments.

Authentication Methods

Mandaitor supports multiple authentication methods:

Method	Header	Use Case
API Key (via SDK)	Authorization: Bearer <tenantId>:<apiKey>	Server-to-server communication, SDK usage
Cognito JWT	Authorization: Bearer <cognitoToken>	Dashboard, widget configuration, admin operations
EUDI Wallet	OpenID4VP session flow	eIDAS 2.0 identity verification (HIGH assurance)
Auth0 JWT	Authorization: Bearer <auth0Token>	Customer-facing app authentication
Okta JWT	Authorization: Bearer <oktaToken>	Enterprise workforce authentication
Entra ID JWT	Authorization: Bearer <entraToken>	Microsoft ecosystem authentication

For most integrations, API Key authentication via the SDK is the recommended approach. The SDK automatically formats the Authorization: Bearer tenantId:apiKey header.

For identity-verified mandates, see the Identity Integration section for EUDI Wallet, Auth0, Okta, and Microsoft Entra ID setup guides.

Obtaining an API Key

API keys are provisioned during the tenant onboarding process. After your tenant is activated, you can generate additional keys via the API:

curl -X POST https://api.mandaitor.io/v1/tenants/{tenantId}/api-keys \
  -H "Authorization: Bearer $COGNITO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "scopes": ["mandates:read", "mandates:write", "verify"]
  }'

The response contains the API key, which is only shown once:

{
  "key_id": "key_01HXY...",
  "api_key": "mk_live_...",
  "name": "production-key",
  "scopes": ["mandates:read", "mandates:write", "verify"],
  "created_at": "2025-01-15T10:30:00Z"
}

Important: Store your API key securely immediately after creation. It cannot be retrieved again.

API Key Scopes

Each API key can be scoped to specific operations. Available scopes are:

Scope	Permissions
mandates:read	List and retrieve mandates
mandates:write	Create, revoke, suspend, and reactivate mandates
verify	Verify actions against mandates
events:read	List and retrieve audit events
tenants:admin	Manage tenant settings, widget configuration, and API keys

Follow the principle of least privilege: only grant the scopes that a specific key actually needs. For example, a verification-only service should use a key with only the verify scope.

Using the SDK

The Mandaitor SDK handles authentication automatically. Pass your API key when initializing the client:

import { MandaitorClient } from "@mandaitor/sdk";

const client = new MandaitorClient({
  apiKey: process.env.MANDAITOR_API_KEY,
  tenantId: "tnt_your_tenant_id",
});

The SDK automatically includes the Authorization: Bearer tenantId:apiKey header in all requests.

Security Best Practices

Never expose keys in client-side code

API keys must be kept on the server side. Never include them in frontend JavaScript, mobile apps, or public repositories.

// ❌ Bad: API key in frontend code
const client = new MandaitorClient({
  apiKey: "mk_live_abc123...", // Exposed to anyone viewing source
  tenantId: "tnt_123",
});

// ✅ Good: API key on the server, proxy requests from frontend
// Server-side (Node.js / Express)
app.post("/api/verify", async (req, res) => {
  const result = await client.verify(req.body);
  res.json(result);
});

Use environment variables

Store API keys in environment variables, not in code:

# .env (never commit this file)
MANDAITOR_API_KEY=mk_live_...
MANDAITOR_TENANT_ID=tnt_...

const client = new MandaitorClient({
  apiKey: process.env.MANDAITOR_API_KEY!,
  tenantId: process.env.MANDAITOR_TENANT_ID!,
});

Rotate keys regularly

Create new API keys periodically and revoke old ones. This limits the impact of a potential key compromise.

A recommended rotation workflow:

1. Generate a new API key with the same scopes.
2. Update your application configuration to use the new key.
3. Deploy the updated configuration.
4. Verify that the new key works correctly.
5. Revoke the old key.

Use separate keys per environment

Maintain separate API keys for development, staging, and production environments. This ensures that a compromised development key cannot affect production data.

Monitor API key usage

Review your audit logs regularly to detect unusual activity patterns. Mandaitor records all API calls with the associated key ID in the audit trail.

Error Responses

Authentication failures return a 401 Unauthorized response:

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Common causes:

• Missing Authorization header
• Invalid or revoked API key
• Malformed Bearer token (expected format: Bearer tenantId:apiKey)
• API key does not have the required scope for the requested operation

For more details on error handling, see the Error Handling Guide.