Authentication

The Embermind API supports two authentication methods. Choose the one that fits your use case.

Overview

Recommendation: Use API Key for all automated integrations. Access Tokens are primarily used by the Admin Panel web interface.

Method 1: API Key (Recommended)

API Keys are permanent credentials that don't expire. Use them for server-to-server communication.

Getting Your API Key

Your API Key is provided by your account manager:

{
    "apiKeyId": "787987b3-7884c-4888-95183-a9889777e",
    "apiKeyTitle": "root",
    "apiKeyValue": "YOUR_API_KEY"
}

Using the API Key

Add the x-api-key header to all requests:

curl -X GET 'https://api.embermind.ch/api/v1/client/profile/me' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Response Example

{
  "id": "f0fab777-fd19-4330-2229-8f4431239a1acf",
  "email": "[email protected]",
  "login": "admin",
  "companyId": "7992110d-617e-40c5-8232-3b9a94e8248ad2f1"
}

Method 2: Access Token

Access Tokens are session-based credentials obtained by logging in with username/password.

Obtain Token

Call the login endpoint:

curl -X POST 'https://api.embermind.ch/api/v1/client/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "loginOrEmail": "[email protected]",
    "password": "your_password"
  }'

Response:

{
  "xAccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use Token in Requests

Add the x-access-token header:

curl -X GET 'https://api.embermind.ch/api/v1/client/profile/me' \
  -H 'Content-Type: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Logout (Optional)

Invalidate the token when done:

curl -X POST 'https://api.embermind.ch/api/v1/client/auth/logout' \
  -H 'Content-Type: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

IP Whitelisting (Optional)

For enhanced security, configure IP whitelisting:

Outbound (your servers → Embermind):
Provide your manager with a list of IP addresses that will make API calls. Requests from other IPs will be rejected.

Inbound (Embermind → your servers):
If you use webhooks, request Embermind's IP addresses and whitelist them in your firewall.

Error Handling

Authentication Errors

Error Response Format

All errors follow this structure:

{
  "error": "error.auth.api_key_incorrect",
  "message": "API key is missing or invalid"
}

Handling Token Expiration

Access tokens expire after a period of inactivity. When you receive error.auth.token_incorrect:

1. Call the login endpoint to get a new token
2. Retry the failed request with the new token

Example retry logic (pseudocode):

async function apiRequest(endpoint, data) {
  let response = await fetch(endpoint, {
    headers: { 'x-access-token': token }
  });
  
  if (response.error === 'error.auth.token_incorrect') {
    token = await refreshToken();
    response = await fetch(endpoint, {
      headers: { 'x-access-token': token }
    });
  }
  
  return response;
}

Security Best Practices

1. Never expose API keys in client-side code — Only use them in server-to-server communication
2. Use environment variables — Don't hardcode credentials in your source code
3. Rotate keys periodically — Contact your manager to issue new API keys
4. Monitor API usage — Check for unusual activity in the Admin Panel
5. Use IP whitelisting — Restrict API access to known IP addresses

Validating Credentials

Check API Key

curl -X POST 'https://api.embermind.ch/api/v1/client/auth/check-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Check Access Token

curl -X POST 'https://api.embermind.ch/api/v1/client/auth/check-token' \
  -H 'Content-Type: application/json' \
  -H 'x-access-token: YOUR_TOKEN'

Success Response:

{
  "valid": true,
  "companyId": "7992110d-617e-40c5-8232-3b9a94e8248ad2f1"
}

Next Steps

• Quick Start — Make your first API request
• Commission Setup — Configure fee calculation
• API Reference — Full API documentation

Need Help?

For authentication issues or credential requests, contact your Embermind account manager.