Authentication

Learn how to securely authenticate your requests to the Approved Contact Texting API using HTTP Basic Authentication.

Security First: All API requests must be made over HTTPS to ensure your credentials are encrypted in transit.

Basic Authentication

The Approved Contact API uses HTTP Basic Authentication. You need to send your credentials (email and password) encoded in Base64 in the Authorization header of every API request.

Creating the Authorization Header

The Authorization header format is:

Authorization: Basic <base64-encoded-credentials>

Where <base64-encoded-credentials> is the Base64 encoding of username:password

Example: Encoding Credentials

# Using curl (handles encoding automatically)
USERNAME="your-email@example.com"
PASSWORD="your-password"

curl -X GET https://api.approvedcontact.com/api/v1/tenants \
  -u "$USERNAME:$PASSWORD"

# Manual encoding
CREDENTIALS=$(echo -n "$USERNAME:$PASSWORD" | base64)
curl -X GET https://api.approvedcontact.com/api/v1/tenants \
  -H "Authorization: Basic $CREDENTIALS"

import base64
import requests

username = "your-email@example.com"
password = "your-password"

# Encode credentials
credentials = base64.b64encode(f"{username}:{password}".encode()).decode()

headers = {
    "Authorization": f"Basic {credentials}"
}

response = requests.get(
    "https://api.approvedcontact.com/api/v1/tenants",
    headers=headers
)

print(response.json())

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

var username = "your-email@example.com";
var password = "your-password";

// Encode credentials
var credentials = Convert.ToBase64String(
    Encoding.ASCII.GetBytes($"{username}:{password}"));

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Basic", credentials);

var response = await client.GetAsync(
    "https://api.approvedcontact.com/api/v1/tenants");

var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);

const axios = require('axios');

const username = 'your-email@example.com';
const password = 'your-password';

// Encode credentials
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

const headers = {
    'Authorization': `Basic ${credentials}`
};

axios.get('https://api.approvedcontact.com/api/v1/tenants', { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.response?.data));

Security Best Practices

Important: Never expose your API credentials in client-side code, public repositories, or log files. Always store them securely using environment variables or secret management systems.

Recommended Practices

Use HTTPS Only: All API requests must use HTTPS. HTTP requests will be rejected.
Store Credentials Securely: Use environment variables, Azure Key Vault, AWS Secrets Manager, or similar services.
Rotate Passwords Regularly: Change your password periodically to minimize risk.
Use Service Accounts: Create dedicated API user accounts separate from personal accounts.
Implement Rate Limiting: Add retry logic with exponential backoff to handle rate limits gracefully.
Monitor Access: Regularly review API access logs for suspicious activity.

Example: Storing Credentials Securely

# Set environment variables
export API_USERNAME="your-email@example.com"
export API_PASSWORD="your-password"

# Use in your application
curl -X GET https://api.approvedcontact.com/api/v1/tenants \
  -u "$API_USERNAME:$API_PASSWORD"

// appsettings.json (for development only, use User Secrets or Key Vault for production)
{
  "ApiCredentials": {
    "Username": "your-email@example.com",
    "Password": "your-password"
  }
}

// In your code
public class ApiClient
{
    private readonly IConfiguration _configuration;
    
    public ApiClient(IConfiguration configuration)
    {
        _configuration = configuration;
    }
    
    public async Task GetAuthenticatedClient()
    {
        var username = _configuration["ApiCredentials:Username"];
        var password = _configuration["ApiCredentials:Password"];
        
        var credentials = Convert.ToBase64String(
            Encoding.ASCII.GetBytes($"{username}:{password}"));
        
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Basic", credentials);
        
        return client;
    }
}

# docker-compose.yml
version: '3.8'
services:
  api-consumer:
    image: your-app:latest
    environment:
      - API_USERNAME=${API_USERNAME}
      - API_PASSWORD=${API_PASSWORD}

# .env file (not committed to version control)
API_USERNAME=your-email@example.com
API_PASSWORD=your-password

Authentication Errors

401 Unauthorized

This error occurs when authentication fails. Common causes:

Missing Authorization Header

{
  "message": "Authorization header is required",
  "title": "Unauthorized",
  "errorCode": "MISSING_AUTHORIZATION"
}

Invalid Credentials

{
  "message": "Invalid credentials",
  "title": "Unauthorized",
  "errorCode": "INVALID_CREDENTIALS"
}

Malformed Authorization Header

{
  "message": "Invalid authorization header format",
  "title": "Unauthorized",
  "errorCode": "INVALID_AUTHORIZATION_FORMAT"
}

Troubleshooting Authentication Issues

Debugging Tips:

Verify your credentials are correct by logging into the portal
Check that the Authorization header is properly formatted
Ensure credentials are Base64 encoded correctly
Confirm you're using HTTPS, not HTTP
Check for extra whitespace in username or password

Testing Authentication

You can test your authentication using the health check endpoint:

curl -X GET https://api.approvedcontact.com/api/v1/health \
  -u "your-email@example.com:your-password"

A successful response indicates your credentials are valid:

{
  "totalDuration": "00:00:00.1234567",
  "status": "Healthy",
  "entries": [...]
}