Authentication

All Taifa Mail API requests require authentication. There are three methods depending on your use case.

Method 1: API Key (recommended for backends)

Best for server-to-server communication, scripts, and CI/CD pipelines.

Create an API key at Settings → API Keys, then send it as a Bearer token:

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

API keys use the tfm_k_ prefix and carry a set of permission scopes. See API Keys for details on creating, scoping and managing keys.

Method 2: JWT Cookie (dashboard sessions)

When you sign into the Taifa Mail dashboard via Google or GitHub OAuth, the server issues a JWT stored in an HttpOnly, Secure, SameSite=Strict cookie. The browser sends this cookie automatically with every request.

You do not need to manage JWT cookies manually. This method is used internally by the dashboard frontend.

The JWT also carries your active workspace, so dashboard requests are automatically scoped to the workspace you are viewing. Besides Google and GitHub OAuth, the dashboard also supports magic-link sign-in and optional two-factor authentication.

OAuth flow

1. User visits /auth/google or /auth/github.
2. Taifa Mail redirects to the OAuth provider.
3. Provider redirects back with an authorization code.
4. Taifa Mail exchanges the code for a user profile.
5. Taifa Mail creates or updates the local user record.
6. Taifa Mail issues a JWT and sets it as an HttpOnly cookie.
7. User is redirected to the dashboard.

JWT details

Method 3: OAuth (AI assistants / MCP)

Taifa Mail is also an OAuth 2.1 authorization server, used by AI assistants that connect through the MCP server.

A client registers via Dynamic Client Registration (RFC 7591) and runs the authorization-code flow with PKCE. The user signs in and approves the connection on a consent screen; the client receives a short-lived mcp_access token. The API accepts that token in the same Authorization: Bearer header as an API key.

Discovery metadata is published at:

• /.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource (served by the MCP server)

Each connection is recorded as a grant. Revoking it from Settings → Connections in the dashboard invalidates the token immediately. You normally never set this up by hand - your AI client runs the whole flow. See the MCP server guide.

Which method to use

Error responses

401 example:

{
  "detail": "Invalid or expired token"
}

403 example:

{
  "detail": "This feature requires the Starter plan or above"
}