인증

API 키(연동에 권장)

API 키는 계정의 멤버에 연결된 개인 액세스 토큰입니다.

설정 → 플러그인 → RolChat API 키에서 만듭니다. 비밀 값은 한 번만 표시되며, 그 후에는 처음 10자만 보입니다. RolChat은 SHA-256 해시만 저장합니다.
형식: rcp_ 뒤에 base64url로 인코딩된 32바이트 난수가 붙으며, 전체 약 45자입니다. 이 접두사로 로그에서 키를 알아보기 쉽고 세션 토큰과도 구분됩니다.
범위: 키를 만들 때 고정된 기능 카탈로그에서 고릅니다. 키는 그것을 만든 멤버보다 많은 일을 할 수 없습니다. 호출할 때마다 해당 기능이 키의 범위에 있는지, 그리고 멤버가 여전히 그 기능을 가지고 있는지 두 조건을 모두 확인합니다. 멤버의 역할을 좁히면 키도 함께 좁아집니다.
수명: 키는 스스로 만료되지 않습니다. 프로필 페이지나 DELETE /api/v1/tokens/:id로 키를 폐기하며, 폐기는 즉시 적용됩니다. 제자리 교체는 없으므로 폐기한 뒤 새 키를 만드세요.
생성과 폐기는 감사 로그에 기록됩니다.

베어러 토큰으로 보냅니다. 별도의 API 키 헤더는 없습니다.

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

플러그인 API 키를 사용한 요청은 분당 300회로 제한됩니다.

JWT 세션

웹 앱과 모바일 SDK는 이메일과 비밀번호(또는 Google, Apple)로 로그인하고 토큰 쌍을 받습니다.

토큰	수명	비고
액세스 토큰	15분	RS256, `/.well-known/jwks.json`의 JWKS로 검증
갱신 토큰	30일	갱신할 때마다 교체됩니다. 교체된 토큰을 재사용하면 체인 전체가 폐기됩니다

클레임: sub(사용자), acc(계정), rl(역할), 사이트별 역할인 경우 sts(허용된 사이트).

POST /auth/login, /auth/refresh, /auth/swap-company, /auth/logout은 아래에 설명하는 X-Account-Id 헤더를 보내면 안 되는 유일한 인증 흐름 엔드포인트입니다.

`X-Account-Id` 헤더

위 네 개를 제외한 모든 인증된 요청에는 작업 대상 계정을 담아야 합니다.

X-Account-Id: <account uuid>

서버는 헤더가 토큰의 acc 클레임(또는 API 키의 계정)과 같은지 확인합니다. 헤더가 없으면 400 missing_required_header, 일치하지 않으면 403 account_context_mismatch입니다. 이 헤더는 클라이언트 버그나 재전송된 토큰이 다른 테넌트의 데이터를 몰래 읽는 일을 막기 위해 존재합니다. 불일치는 어떤 쿼리도 실행되기 전에 거부되며, 모든 로그 줄은 토큰을 디코딩하지 않고도 계정에 귀속됩니다.

여러 회사에 속한 사용자

한 사람이 여러 회사에 속할 수 있습니다. 회사마다 자체 토큰(자체 acc 클레임)이 있습니다. 전환하려면 다음과 같이 합니다.

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

대상은 호출자의 available_companies(로그인 시 반환) 중 하나여야 하며, 그렇지 않으면 403 forbidden입니다. 응답은 대상 회사로 범위가 지정된 새 액세스 토큰과 갱신 토큰 쌍입니다. 이전 갱신 토큰은 폐기되고 auth.account.swapped 감사 이벤트가 기록됩니다.

다단계 인증

TOTP 기반 MFA는 멤버별로 등록하고 계정별로 필수로 지정할 수 있습니다. 켜져 있으면 POST /auth/login이 챌린지를 반환하고 세션은 POST /auth/mfa/verify로 완료됩니다. 백업 코드는 등록할 때 발급됩니다.

로그인 보호

로그인 경로는 IP당 분당 10회, 이메일당 15분당 5회로 제한됩니다.
로그인에 열 번 실패하면 해당 이메일이 30분 동안 잠기며, 응답에 code: account_locked가 포함됩니다.
reCAPTCHA는 작업(가입, 로그인, 비밀번호 재설정)별로 켤 수 있으며, 공개 부트스트랩 구성은 GET /api/v1/captcha에서 제공됩니다.

인증