Skip to main content

Authentication

MessagePipe supports two authentication methods depending on the context:

Bearer Token: used for dashboard and management operations such as creating projects, managing templates and configuring providers. Obtained by signing in via /auth/signin and passed in the Authorization header:

Authorization: Bearer your-jwt-token

API Key: used for sending emails, messages and push notifications from your application. Scoped to a specific project and passed via the x-api-key header:

x-api-key: your-api-key-here

Most internal/management endpoints require a Bearer token while Sending endpoints accept either.

API Key Authentication​

API keys are scoped to specific projects and can be managed independently.

Use Cases:

  • Sending emails, messages and push notifications
  • Template preview
  • Template update

Getting Your API Key​

1. Create a Project​

First, create a project in your MessagePipe dashboard:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/projects" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App"
  }'

2. Generate an API Key​

Create an API key for your project:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/projects/PROJECT_ID/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key"
  }'

Response:

{
  "message": "API key created successfully. This is the only time you will be able to see the raw API key. Please copy and store it securely. You will not be able to retrieve it again",
  "key": "mzl_1234567890abcdef"
}

⚠️ Important: The API key is only shown once. Store it securely.

API Key Management​

List API Keys​

curl -X GET "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/projects/PROJECT_ID/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update API Key​

curl -X PUT "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/projects/PROJECT_ID/api-keys/API_KEY_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "isActive": false
  }'

Delete API Key​

curl -X DELETE "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/projects/PROJECT_ID/api-keys/API_KEY_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Account Management​

Sign Up​

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "firstName": "John",
    "lastName": "Doe"
  }'

Sign In​

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/signin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "expiresIn": 3600
}

Refresh Token​

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

Get Current User Profile​

curl -X GET "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Password Management​

Request Password Reset​

Send a reset link to a user's email:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/request-password-reset" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Response:

{
  "message": "Password reset email sent"
}

Reset Password​

Use the token received in the reset email:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "newPassword": "your-new-password"
  }'

Change Password​

For authenticated users who want to change their password:

curl -X POST "https://mzl-email-template-engine.dev.zero.mangozestlabs.com/auth/change-password" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "old-password",
    "newPassword": "new-password"
  }'

Security Best Practices​

API Key Security​

  • Never expose API keys in client-side code
  • Store API keys as environment variables
  • Use different API keys for different environments
  • Regularly rotate API keys
  • Disable unused API keys immediately

Environment Variables​

# .env file
MESSAGEPIPE_API_KEY=mzl_1234567890abcdef
MESSAGEPIPE_BASE_URL=https://mzl-email-template-engine.dev.zero.mangozestlabs.com

Error Responses​

Invalid API Key (401)​

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

API Key Disabled (401)​

{
  "statusCode": 401,
  "message": "API key is disabled",
  "error": "Unauthorized"
}

Expired JWT Token (401)​

{
  "statusCode": 401,
  "message": "Token has expired",
  "error": "Unauthorized"
}