Authentication

Learn how to authenticate with the MsGine API using API keys.

Overview

All MsGine API requests must be authenticated using an API key passed in the X-Api-Key header:

X-Api-Key: YOUR_API_KEY

Getting Your API Key

1. Sign in to your MsGine account
2. Navigate to the Developer Dashboard
3. Click Generate New Token
4. Copy the key immediately (it won't be shown again)
5. Store it securely in your environment variables

Security Warning

Never expose your API key in:

• Client-side code (browser JavaScript)
• Public repositories
• Version control systems
• Log files or error messages

Always store keys in environment variables or secure secret management systems.

Using API Keys

HTTP Requests

Include the key in the X-Api-Key header:

curl -X POST https://api.msgine.net/api/v1/developers/sms \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+256701521269",
    "message": "Hello from MsGine!"
  }'

JavaScript/TypeScript

const response = await fetch('https://api.msgine.net/api/v1/developers/sms', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.MSGINE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+256701521269',
    message: 'Hello from MsGine!'
  })
})

Python

import os
import requests

headers = {
    'X-Api-Key': os.environ['MSGINE_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.msgine.net/api/v1/developers/sms',
    headers=headers,
    json={
        'to': '+256701521269',
        'message': 'Hello from MsGine!'
    }
)

PHP

<?php
$apiKey = getenv('MSGINE_API_KEY');

$ch = curl_init('https://api.msgine.net/api/v1/developers/sms');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-Api-Key: $apiKey",
    'Content-Type: application/json'
]);

Using the Official SDK

The SDK handles authentication automatically:

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiKey: process.env.MSGINE_API_KEY!,
})

// SDK automatically includes the key in all requests
await client.sms.send({
  to: '+256701521269',
  message: 'Hello!'
})

Token Management

Creating Tokens

You can create multiple API keys for different purposes:

• Development: For testing and development
• Production: For live applications
• CI/CD: For automated deployments
• Third-party: For external integrations

Each key can be revoked independently without affecting others.

Revoking Tokens

If a key is compromised:

1. Navigate to the Developer Dashboard
2. Find the compromised key
3. Click Revoke
4. Generate a new key
5. Update your application with the new key

TIP

Rotate API keys regularly as a security best practice.

Authentication Errors

401 Unauthorized

Occurs when the API key is invalid or missing.

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

Solutions:

• Verify the key is correct
• Check the key hasn't been revoked
• Ensure the X-Api-Key header is properly set

403 Forbidden

Occurs when the key lacks required permissions.

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions for this operation"
  }
}

Solutions:

• Generate a new key with appropriate permissions
• Contact support if you need additional access

Security Best Practices

1. Use Environment Variables

Never hardcode keys in your source code:

// ❌ Bad
const client = new MsGineClient({
  apiKey: 'msgine_live_abc123...'
})

// ✅ Good
const client = new MsGineClient({
  apiKey: process.env.MSGINE_API_KEY!,
})

2. Server-Side Only

Only use API keys in server-side code:

// ✅ Good - Server code only
import { MsGineClient } from '@msgine/sdk'
const client = new MsGineClient({
  apiKey: process.env.MSGINE_API_KEY!,
})

3. Key Rotation

Rotate keys regularly:

• Production keys: Every 90 days
• Development keys: As needed
• Immediately: If a key is compromised

4. Secure Storage

• Development: .env files (add to .gitignore)
• Production: Environment variables, secret managers (AWS Secrets Manager, Azure Key Vault, etc.)
• CI/CD: Encrypted secrets

Testing Authentication

Test your authentication setup:

curl https://api.msgine.net/api/v1/account \
  -H "X-Api-Key: YOUR_API_KEY"

Successful response:

{
  "id": "acc_1234567890",
  "email": "user@example.com",
  "balance": 5000,
  "currency": "UGX"
}

Next Steps

• REST API - API reference and examples
• Rate Limits - Understanding rate limits
• Webhooks - Configure delivery notifications