Authentication
Overview

Authentication

Every request to the TalkNTalk API must include two security headers: your API key and your Organisation ID. Both must be present and must match — a leaked key alone cannot be used without the correct organisation ID.

Required Headers

HeaderValueDescription
AuthorizationBearer tk_live_…Your secret API key
X-Organisation-Id3fa85f64-…Your organisation's UUID
Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Both headers are required on every request to /v1/*.

Where to Find Your Organisation ID

Your organisation UUID is returned by the verify endpoint (GET /v1/) and is also available in your dashboard under Settings → Organisation.

Verifying Your Key

Before building your integration, confirm both credentials work together:

curl https://api.v1.talkntalk.africa/v1/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Success — 200 OK

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

Code Examples

curl https://api.v1.talkntalk.africa/v1/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Error Responses

All errors follow the same shape:

{
  "detail": "Human-readable error message."
}
StatusWhen it occurs
401 UnauthorizedAuthorization header missing, malformed, key revoked, or X-Organisation-Id missing / mismatched
403 ForbiddenKey is valid but you don't have permission for this action
429 Too Many RequestsRate limit exceeded — back off and retry
500 Internal Server ErrorSomething went wrong on our end — contact support if it persists

401 — Missing org header

{
  "detail": "Missing 'X-Organisation-Id' header. Pass your organisation UUID alongside your API key."
}

401 — Org mismatch

{
  "detail": "Organisation ID does not match this API key. Check your X-Organisation-Id header."
}

401 — Invalid key

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

401 — Missing Authorization header

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

Keep Your Credentials Safe

  • Store both values in environment variables or a secrets manager — never in source code
  • Do not include them in frontend/client-side code
  • Rotate your API key immediately if you suspect it has been leaked — see API Keys
IntroductionVerify Key