Authentication

Every request to the TalkNTalk API must include a valid API key. Your key identifies both your account and your organisation — no extra headers required.

How It Works

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

Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That's it. The key is bound to one organisation, so the API automatically scopes all responses to your data.

Verifying Your Key

Before building your integration, confirm your key is valid with a quick ping:

curl https://api.talkntalk.africa/v1/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Success — 200 OK

{
  "api": "TalkNTalk",
  "version": "v1",
  "organisation": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Acme Corp",
    "slug": "acme-corp"
  }
}

If you see this response your key is active and correctly scoped to your organisation.

Code Examples

curl https://api.talkntalk.africa/v1/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Error Responses

All errors follow the same shape:

{
  "detail": "Human-readable error message."
}

Status	When it occurs
`401 Unauthorized`	`Authorization` header is missing, malformed, or the key is revoked
`403 Forbidden`	Key is valid but you don't have permission for this action
`429 Too Many Requests`	Rate limit exceeded — back off and retry
`500 Internal Server Error`	Something went wrong on our end — contact support if it persists

401 Example

{
  "detail": "Invalid or revoked API key."
}

401 — Missing header

{
  "detail": "Authentication credentials were not provided."
}

Keep Your Key Safe

Store it in an environment variable or secrets manager — never in source code
Do not include it in frontend/client-side code
Rotate it immediately if you suspect it has been leaked — see API Keys for how to regenerate

Introduction Verify Key