인증

모든 요청은 API Key를 Bearer 토큰으로 실어 인증합니다.

Authorization: Bearer blumnb-xxxx-xxxx-xxxx

키는 blumnb- 접두사로 시작합니다.
키는 톡브릿지 센터에서 발급·회전·폐기합니다. 유출 시 톡브릿지 센터에서 즉시 회전하세요.
키는 브랜드(brandKey) 스코프입니다 — 인가된 브랜드의 상담만 접근할 수 있습니다(테넌트 격리).

권한 스코프

스코프	할 수 있는 것
BrandRead	조회 — `me`, `rooms`, `rooms/{userKey}/messages`, `conversations`, `conversation`, `profile`, `sysmsg`, `channel/*`(GET)
BrandWrite	위 조회 + 발신 — `send`, `send/rich`, `send/attachments`, `send/image`, `delete`, `end`, `end-with-bot`, `block`, `unblock`, `upload/*`
Admin	위 전부 + 채널 설정 변경 — `channel/domain`(POST), `channel/chat`(POST), `channel/schedule`(POST). 테넌트의 모든 브랜드에 적용

발신 API는 BrandWrite, 채널 설정 변경 3종은 Admin 이 필요합니다(BrandWrite 로 호출하면 403 FORBIDDEN). 조회만 하는 통합이라면 BrandRead 키를 쓰세요.

브랜드 검증

토큰이 대상 브랜드에 인가돼 있지 않으면 403 NO_BRAND_SCOPE 로 거부됩니다. 요청 바디/쿼리의 brandKey(또는 brand)는 me 응답의 brands 목록에 포함된 값이어야 합니다.

예시

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": "상담톡 채널",   "brandKey": "mybrand-1a2b3c", "brandName": "마이브랜드" },
    { "key": "ch-5d6e7f", "type": "Line",      "name": "LINE 공식계정", "brandKey": "mybrand-1a2b3c", "brandName": "마이브랜드" }
  ]
}

brands: 이 키로 쓸 수 있는 Brand Key 목록입니다. 채널마다 하나씩이라, 한 브랜드에 채널이 여러 개면 값도 여러 개입니다.
channels: 같은 목록의 상세입니다. key 는 brands 의 값과 같고, 채널 종류(type: KakaoChat·Line·NaverTalk)·채널 이름·소속 브랜드를 함께 줍니다.
- channels[].brandKey 는 브랜드 자체의 식별자로, 요청의 brandKey 에 넣는 값이 아닙니다. 요청에는 key 를 넣습니다.

노트

me 응답에는 봉투가 없습니다

다른 API 는 { ok, code, message, … } 봉투로 응답하지만 GET /api/agent/me 는 봉투 없이 { name, scope, brands, channels } 를 그대로 돌려줍니다. 키가 무효하면 본문 없이 401 입니다.

userKey 형식

userKey 는 카카오가 채널(브랜드)별로 발급하는 고객 식별자입니다. 서식을 가정하지 말고 문자열 그대로 저장·비교하세요.

문자 집합: 영문 대소문자·숫자·_·-. 길이는 가변(실측 12자 안팎)이며 대소문자를 구분합니다. 예: Ab3d_x9Kq2Lm
채널 경계를 넘어 동일인으로 가정하지 마세요 — 같은 사람이라도 브랜드가 다르면 다른 값입니다.
차단·해제로는 바뀌지 않고, 고객이 카카오톡을 탈퇴·재가입하면 바뀝니다.
수신 웹훅의 userKey 와 발신 API 의 userKey 는 같은 값입니다 — 검증 정규식을 두려면 ^[A-Za-z0-9_-]{1,64}$ 정도로 느슨하게 두세요.

연동 키 3종 — 서명 시크릿과는 다릅니다

API Key(blumnb-)는 REST 호출 인증용입니다. 수신 웹훅의 무결성을 검증하는 서명 검증 키(whsec_) 는 별개이며, 웹훅 서명 검증에서 다룹니다. 여기에 대상 브랜드를 지정하는 Brand Key(brandKey)까지 더해 세 값이 함께 연동 보안을 이룹니다 — 세 키 모두 톡브릿지 센터 개발자 모드 「연동 키 안내」 에서 확인합니다.

권한 스코프​

브랜드 검증​

예시​

userKey 형식​

권한 스코프

브랜드 검증

예시

userKey 형식