API Keys

API keys let you authenticate with the Taifa Mail API from your backend, scripts, or CI/CD pipelines without using browser-based login.

Creating an API key

1. Go to Developer → API Keys.
2. Click Create API Key.
3. Give the key a descriptive name, for example "Service portal production" or "ICT staging tests".
4. Choose the permission scopes the key should carry (see Permissions below). New keys default to the send scope.
5. Click Create.
6. Copy the key immediately.

Key format

All Taifa Mail API keys use the prefix tfm_k_ followed by a random string:

tfm_k_7f3a9b2c1d4e5f6a8b9c0d1e2f3a4b5c

The prefix makes keys easy to identify in logs and secret scanners. Only a short prefix of each key is stored on our side; the rest is hashed, so the full key cannot be recovered after creation.

Using an API key

Pass the key in the Authorization header as a Bearer token:

curl https://govconnect.ke/v1/emails \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_": {"email": "info@health.go.ke", "name": "Ministry of Health"},
    "to": [{"email": "citizen@example.com", "name": "Jane"}],
    "subject": "Test message from Taifa Mail",
    "html": "<p>This is a test message from an official address.</p>",
    "text": "This is a test message from an official address."
  }'

Python example

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/emails",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
    json={
        "from_": {"email": "info@health.go.ke", "name": "Ministry of Health"},
        "to": [{"email": "citizen@example.com", "name": "Jane"}],
        "subject": "Test message from Taifa Mail",
        "html": "<p>This is a test message from an official address.</p>",
        "text": "This is a test message from an official address.",
    },
)
print(response.json())

Node.js example

const response = await fetch("https://govconnect.ke/v1/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from_: { email: "info@health.go.ke", name: "Ministry of Health" },
    to: [{ email: "citizen@example.com", name: "Jane" }],
    subject: "Test message from Taifa Mail",
    html: "<p>This is a test message from an official address.</p>",
    text: "This is a test message from an official address.",
  }),
});
const data = await response.json();
console.log(data);

Permissions

Every API key carries a list of permission scopes, set when the key is created. A key only grants the scopes it was issued with - it is not a full-access credential. New keys default to the send scope.

Each key's scopes are shown next to it in Developer → API Keys, along with its prefix, creation date, and when it was last used. Scope a key down to what the integration actually needs, and use separate keys for separate systems so you can revoke one without affecting the rest.

Revoking a key

1. Go to Developer → API Keys.
2. Click Delete next to the key you want to revoke.
3. Confirm the deletion.

Revocation takes effect immediately - the key is deactivated and any request using it is rejected. Revoked keys are removed from the list and cannot be reactivated.

Security best practices

• Never commit API keys to version control. Use environment variables or a secrets manager.
• Use different keys for production and staging environments.
• Delete keys that are no longer in use.
• Monitor your API usage in Developer → API Keys for unexpected activity.