Authentication

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

Overview

All MsGine API requests must be authenticated using an API token passed in the Authorization header with the Bearer scheme.

Authorization: Bearer YOUR_API_TOKEN

Getting Your API Token

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

Security Warning

Never expose your API token in:

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

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

Using API Tokens

HTTP Requests

Include the token in the Authorization header:

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

JavaScript/TypeScript

const response = await fetch('https://api.msgine.net/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MSGINE_API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+256701521269',
    message: 'Hello from MsGine!'
  })
})

Python

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["MSGINE_API_TOKEN"]}',
    'Content-Type': 'application/json'
}

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

PHP

<?php
$token = getenv('MSGINE_API_TOKEN');

$ch = curl_init('https://api.msgine.net/api/v1/messages/sms');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $token",
    'Content-Type: application/json'
]);

Using the Official SDK

The SDK handles authentication automatically:

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!
})

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

Token Management

Creating Tokens

You can create multiple API tokens for different purposes:

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

Each token can be revoked independently without affecting others.

Revoking Tokens

If a token is compromised:

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

TIP

Rotate tokens regularly as a security best practice.

Token Scopes

API tokens have different permission scopes:

Scope	Description
messages:send	Send SMS messages
messages:read	View message history
account:read	View account information
webhooks:manage	Create and manage webhooks

Tokens are created with all scopes by default. Custom scopes can be configured in the dashboard.

Authentication Errors

401 Unauthorized

Occurs when the API token is invalid or missing.

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

Solutions:

• Verify the token is correct
• Check the token hasn't been revoked
• Ensure the Authorization header is properly formatted

403 Forbidden

Occurs when the token lacks required permissions.

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

Solutions:

• Check the token has the required scope
• Generate a new token with appropriate permissions
• Contact support if you need additional access

Security Best Practices

1. Use Environment Variables

Never hardcode tokens in your source code:

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

// ✅ Good
const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!
})

2. Server-Side Only

Only use API tokens in server-side code:

// ❌ Bad - Browser code
// Never expose tokens in frontend JavaScript
const token = 'msgine_live_abc123...'

// ✅ Good - Server code
// Use tokens only in backend services
import { MsGineClient } from '@msgine/sdk'
const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!
})

3. Token Rotation

Rotate tokens regularly:

• Production tokens: Every 90 days
• Development tokens: As needed
• Immediately: If a token is compromised

4. Secure Storage

Store tokens securely:

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

5. Least Privilege

Use tokens with minimal required scopes:

// Only create tokens with the scopes you need
// If you only send messages, don't include webhooks:manage scope

Testing Authentication

Test your authentication setup:

curl https://api.msgine.net/api/v1/account \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Successful response:

{
  "id": "acc_1234567890",
  "email": "user@example.com",
  "balance": 25.00,
  "currency": "USD"
}

Next Steps

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