Authentication

Every request is authenticated by sending the API Key as a Bearer token.

Authorization: Bearer blumnb-xxxx-xxxx-xxxx

• Keys start with the blumnb- prefix.
• Keys are issued, rotated, and revoked in TalkBridge Center. If a key is leaked, rotate it immediately in TalkBridge Center.
• Keys are scoped to a brand (brandKey) — you can only access consultations of the brands the key is authorized for (tenant isolation).

Permission scopes

Scope	What it can do
BrandRead	Read — me, rooms, rooms/{userKey}/messages, conversations, conversation, profile, sysmsg, channel/*(GET)
BrandWrite	Everything above + sending — send, send/rich, send/attachments, send/image, delete, end, end-with-bot, block, unblock, upload/*
Admin	Everything above + channel settings changes — channel/domain(POST), channel/chat(POST), channel/schedule(POST). Applies to every brand in the tenant

The outbound APIs require BrandWrite; the three channel settings changes require Admin (a BrandWrite key gets 403 FORBIDDEN). If your integration is read-only, use a BrandRead key.

Brand validation

If the token is not authorized for the target brand, the request is rejected with 403 NO_BRAND_SCOPE. The brandKey (or brand) in the request body/query must be a value included in the brands list of the me response.

Example

curl https://api.talkbridge.io/api/agent/me \
  -H "Authorization: Bearer blumnb-xxxx-xxxx-xxxx"

{
  "name": "My Brand Agent",
  "scope": "BrandWrite",
  "brands": ["mybrand", "ch-5d6e7f"],
  "channels": [
    { "key": "mybrand",   "type": "KakaoChat", "name": "KakaoTalk channel",     "brandKey": "mybrand-1a2b3c", "brandName": "My Brand" },
    { "key": "ch-5d6e7f", "type": "Line",      "name": "LINE official account", "brandKey": "mybrand-1a2b3c", "brandName": "My Brand" }
  ]
}

• brands: the Brand Keys this key can use. There is one per channel, so a brand with several channels has several values.
• channels: details of the same list. key equals the value in brands, alongside the channel type (type: KakaoChat, Line, NaverTalk), channel name and owning brand.
  • channels[].brandKey identifies the brand itself and is not the value to put in a request's brandKey. Use key in requests.

note

The me response has no envelope

Other APIs respond with a { ok, code, message, … } envelope, but GET /api/agent/me returns { name, scope, brands, channels } without one. An invalid key gets a 401 with no body.

userKey format

userKey is the customer identifier that Kakao issues per channel (brand). Do not assume a format — store and compare it as an opaque string.

• Character set: ASCII letters, digits, _, and -. Variable length (around 12 characters in practice), case-sensitive. Example: Ab3d_x9Kq2Lm
• Never assume the same person across channels — the same customer gets a different value on a different brand.
• It does not change on block/unblock; it changes if the customer leaves and rejoins KakaoTalk.
• The userKey in the inbound webhook and the userKey in the outbound API are the same value — if you validate it with a regex, keep it loose, e.g. ^[A-Za-z0-9_-]{1,64}$.

The three integration keys — this is different from the signing secret

The API Key (blumnb-) is for REST call authentication. The signature verification key (whsec_) that verifies the integrity of inbound webhooks is separate and is covered in Webhook signature verification. Together with the Brand Key (brandKey) that selects the target brand, these three values make up integration security — all three are shown in the "Integration keys" card in Developer mode of TalkBridge Center.