Authentication

MAES Platform uses API Keys for programmatic API access.

Using the SDK

The SDK handles authentication automatically:

import { MaesClient } from '@nuvoni/maes-sdk';

const client = new MaesClient({
  apiKey: process.env.MAES_API_KEY!,
  projectId: process.env.MAES_PROJECT_ID!,
});

// SDK automatically includes Authorization header
const { docs } = await client.cards.list();

API Keys

Key Types

Type	Prefix	Environment	Use Case
Sandbox	sk_sandbox_*	Sandbox	Testing & development
Production	sk_live_*	Production	Live MAES operations

Key Format

sk_{environment}_{random_base64url_string}

Example: sk_sandbox_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789

• Total length: ~54 characters
• Random portion: 43 characters (256 bits of entropy)

Creating API Keys

Via Dashboard

1. Go to https://maes-platform.nuvoni.eu
2. Open your project
3. Navigate to Sandbox or Production environment
4. Click the "Integrate" tab
5. Click "Create API Key"
6. Copy the key immediately

warning

The full API key is only shown once at creation. Store it securely.

Key Storage

• The platform stores only a SHA-256 hash of your key
• The prefix (sk_sandbox_abc12345) is stored for identification
• We cannot recover lost keys — you must create a new one

Environment Detection

The SDK automatically detects the environment from your API key:

const client = new MaesClient({
  apiKey: 'sk_sandbox_xxxxx',
  projectId: 'project-id',
});

console.log(client.environment); // 'sandbox'

API Key	Environment
sk_sandbox_*	sandbox
sk_live_*	production

info

You cannot use a sandbox key to access production cards, and vice versa.

Error Handling

import { MaesAuthenticationError, MaesPermissionError } from '@nuvoni/maes-sdk';

try {
  await client.cards.list();
} catch (error) {
  if (error instanceof MaesAuthenticationError) {
    // Invalid or expired API key
    console.error('Authentication failed:', error.message);
  }

  if (error instanceof MaesPermissionError) {
    // API key doesn't have access to this project
    console.error('Permission denied:', error.message);
  }
}

Revoking Keys

You can revoke an API key at any time from the dashboard:

1. Go to the Integrate tab in your environment
2. Click "Revoke" next to the API key
3. Confirm the action

danger

Revoked keys immediately stop working. This action cannot be undone.

Security Best Practices

Do's ✅

• Store keys in environment variables

  # .env
  MAES_API_KEY=sk_live_xxxxx
  MAES_PROJECT_ID=your-project-id

• Use secrets management (AWS Secrets Manager, HashiCorp Vault, etc.)

• Rotate keys periodically — Create new key, update apps, revoke old key

• Use sandbox keys for development — Never test with production keys

Don'ts ❌

• Never commit keys to git

  # .gitignore
  .env
  .env.local

• Never expose in client-side code

  // ❌ WRONG - Key visible in browser
  const client = new MaesClient({ apiKey: 'sk_live_xxxxx' });
  
  // ✅ RIGHT - Call from server-side only
  // Frontend → Your Backend → MAES API

• Never log API keys

  // ❌ WRONG
  console.log(`Using key: ${apiKey}`);
  
  // ✅ RIGHT
  console.log('Using key: sk_live_***');