API Keys API

Base URL: https://govconnect.ke/v1

All endpoints require authentication via API Key or JWT cookie.

Create an API key

POST /v1/api-keys/

Creates a new API key for programmatic access to the Taifa Mail API. The raw key is returned only once in the response. Store it securely.

Request body:

{
  "name": "Production backend",
  "permissions": ["send"]
}

Field	Type	Required	Default	Description
`name`	string	Yes	--	A human-readable name for the key.
`permissions`	string[]	No	`["send"]`	Permissions granted to this key.

Available permissions

Keys are deny-by-default: a route protected by a scope only accepts a key that carries that scope. The canonical scopes are:

Scope	Description
`emails:send`	Send transactional and batch emails.
`emails:read`	Read emails, events, and search.
`domains:read`	Read domains and their DNS records.
`domains:write`	Create, verify, and manage domains.
`contacts:read`	Read contact lists and contacts.
`contacts:write`	Create and modify contacts and lists.
`webhooks:read`	Read webhook endpoints and deliveries.
`webhooks:write`	Create and manage webhook endpoints.
`analytics:read`	Read analytics.

You can also store group aliases in permissions, which expand to the scopes above: send (the historic default) expands to emails:send, read to emails:read, emails to both email scopes, domains, contacts, and webhooks to their read+write pair, and *, all, admin, or full to every canonical scope.

When permissions is omitted it defaults to ["send"], granting emails:send only.

Response (201 Created):

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Production backend",
  "key": "tfm_k_3f9a1c2b8e7d6045a1b2c3d4e5f60718293a4b5c",
  "key_prefix": "3f9a1c2b",
  "permissions": ["send"],
  "created_at": "2026-04-10T08:00:00Z"
}

The full key value starts with tfm_k_ and is passed as Authorization: Bearer tfm_k_.... The key_prefix is the first 8 characters after the tfm_k_ prefix and is used to identify the key in list responses.

The key field is only returned when the key is created. It cannot be retrieved again. If you lose it, revoke the key and create a new one.

cURL

curl -X POST https://govconnect.ke/v1/api-keys/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "permissions": ["send"]
  }'

Python

import requests
 
response = requests.post(
    "https://govconnect.ke/v1/api-keys/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"},
    json={
        "name": "Production backend",
        "permissions": ["send"]
    }
)
 
data = response.json()
print(data["key"])  # Store this securely

Node.js

const response = await fetch("https://govconnect.ke/v1/api-keys/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tfm_k_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production backend",
    permissions: ["send"],
  }),
});
 
const data = await response.json();
console.log(data.key); // Store this securely

List API keys

GET /v1/api-keys/

Returns an array of active API keys for the authenticated account. The raw key value is never returned in list responses; only the prefix is shown.

curl https://govconnect.ke/v1/api-keys/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response:

[
  {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "Production backend",
    "key_prefix": "3f9a1c2b",
    "permissions": ["send"],
    "is_active": true,
    "last_used_at": "2026-04-10T12:30:00Z",
    "created_at": "2026-04-10T08:00:00Z"
  },
  {
    "id": "b2c3d4e5-6789-01bc-defg-2345678901bc",
    "name": "Staging key",
    "key_prefix": "7c4e2d10",
    "permissions": ["send"],
    "is_active": true,
    "last_used_at": null,
    "created_at": "2026-04-09T14:00:00Z"
  }
]

Python

import requests
 
response = requests.get(
    "https://govconnect.ke/v1/api-keys/",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
for key in response.json():
    print(f"{key['name']} - active: {key['is_active']}")

Node.js

const response = await fetch("https://govconnect.ke/v1/api-keys/", {
  headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
});
 
const data = await response.json();
data.forEach((key) => {
  console.log(`${key.name} - active: ${key.is_active}`);
});

Deactivate an API key

DELETE /v1/api-keys/{key_id}

Permanently deactivates an API key. Any requests made with this key after deactivation will receive a 401 Unauthorized response.

Parameter	Type	Description
`key_id`	UUID (path)	The ID of the API key to deactivate.

curl -X DELETE https://govconnect.ke/v1/api-keys/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

Response (204 No Content):

No response body.

Python

import requests
 
response = requests.delete(
    "https://govconnect.ke/v1/api-keys/a1b2c3d4-5678-90ab-cdef-1234567890ab",
    headers={"Authorization": "Bearer tfm_k_YOUR_API_KEY"}
)
 
assert response.status_code == 204

Node.js

const response = await fetch(
  "https://govconnect.ke/v1/api-keys/a1b2c3d4-5678-90ab-cdef-1234567890ab",
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer tfm_k_YOUR_API_KEY" },
  }
);
 
console.log(response.status); // 204

Deactivating a key is irreversible. If you need access again, create a new key. Deactivated keys are excluded from the list response.

Errors

Status	Description
`401 Unauthorized`	Missing or invalid authentication.
`404 Not Found`	The specified key ID does not exist or does not belong to your account.

API Keys API

On this page