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

Permission	Description
`send`	Send transactional and batch emails.

Additional permissions will be added in future releases. For now, send is the only available permission and is assigned by default.

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.

Plan limits

The number of API keys you can create depends on your plan:

Plan	Max API keys
Free	2
Starter	5
Pro	15
Business	50

Errors

Status	Description
`401 Unauthorized`	Missing or invalid authentication.
`403 Forbidden`	You have reached the maximum number of API keys for your plan.
`404 Not Found`	The specified key ID does not exist or does not belong to your account.

API Keys API

On this page