API 키와 스코프

Sursa API로 보내는 모든 요청에는 조직의 API 키를 사용해요. 키는 사람이 아니라 조직에 속해요. 키를 만든 직원이 퇴사해도 키는 계속 동작하며, 키로 할 수 있는 일은 키 자체에 설정해요.

키로 할 수 있는 일

키의 설정 세 가지가 그 키로 보낸 요청이 무엇을 보고 바꿀 수 있는지 정해요. 각 설정은 다른 설정의 범위를 좁히기만 해요.

설정	제어하는 내용
역할(Role)	`admin`, `editor`, `verifier`, `viewer` 중 하나로, 사람에게 주는 역할과 같아요. 키는 그 역할의 사용자가 할 수 있는 일을 할 수 있어요.
스코프(Scopes)	키가 호출할 수 있는 API 영역이에요. 예: `cards:read`, `webhooks:manage`. 키 스코프를 참고하세요.
데이터 프로필(Data profile)	선택 사항이에요. 그 프로필이 있는 사용자처럼, 프로필이 허용하는 지식 카테고리로 키를 제한해요.

키를 일부 컬렉션으로 제한하거나 만료일을 지정할 수도 있어요. 이 제한을 벗어난 요청은 실패해요. 스코프가 없으면 403 상태와 api_keys.scope 코드를 반환하고, 키가 볼 수 없는 객체에는 존재하지 않는 객체와 똑같이 404를 반환해요.

연동 시스템마다 필요한 가장 좁은 역할과 스코프로 별도의 키를 주세요. 문서를 쓰기만 하는 동기화 작업에는 admin 역할이 필요 없고, 보고서 작업에는 쓰기 스코프가 필요 없어요.

키 만들기

조직 관리자는 Sursa의 Administration → API keys(관리 → API 키)에서 키를 만들거나, admin 역할이 있는 키나 세션으로 POST /v1/api-keys를 호출해 만들어요.

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

응답의 key 필드에 키 값이 담겨요. 키 값은 한 번만 표시돼요. Sursa는 키의 해시만 보관하므로 다시 보여 줄 수 없어요. 키는 kb_ 뒤에 43자가 붙은 형태이며, 키를 서로 구별할 수 있도록 앞부분(prefix)이 키 목록에 표시돼요.

scopes 값을 생략하면 키는 역할의 스코프를 받아요. 범위를 더 좁히려면 scopes 값을 보내세요. expires_at 값을 생략하면 키는 만료되지 않아요.

키 안전하게 보관하기

키는 시크릿 관리자나 서비스의 환경 변수에 보관하고, 소스 코드에는 절대 넣지 마세요.
키는 서버에서만 사용하세요. Sursa는 브라우저에서 보낸 요청도 받지만(CORS가 열려 있어요), 웹 페이지에 들어간 키는 그 페이지를 여는 모든 사람에게 보여요.
키를 URL에 넣어 보내지 마세요. 키는 Authorization 헤더로만 보내세요.
키가 유출되면 즉시 폐기하고 새 키를 만드세요.

키 확인하기

GET /v1/me는 키, 키의 역할, 실제로 적용되는 스코프, 데이터 프로필, 만료일, 호출 한도를 반환해요. 스코프와 관계없이 유효한 키라면 어떤 키로든 호출할 수 있으므로, 연동의 연결 테스트나 403 오류의 원인을 조사할 때 사용하세요.

키 교체하기

교체는 연동을 멈추지 않고 키를 바꾸는 방법이에요. 가장 빠른 방법은 키를 재발급하는 거예요. POST /v1/api-keys/{key_id}/roll은 같은 키에 새 값을 발급하며, 역할, 스코프, 컬렉션, 만료일은 그대로 유지돼요. 이전 값은 overlap_hours 동안(기본 24시간, 최대 168시간) 계속 동작하므로 그사이에 새 값을 배포하면 돼요. POST /v1/api-keys/{key_id}/revoke-previous로 유예 기간을 일찍 끝낼 수도 있어요.

키를 재발급하는 대신 다른 키로 바꾸려면 다음 순서를 따르세요.

같은 역할, 스코프, 데이터 프로필로 새 키를 만드세요.
연동 시스템에 새 키를 배포하세요.
이전 키가 더 이상 쓰이지 않을 때까지 Administration → API keys(또는 GET /v1/api-keys의 last_used 값)에서 지켜보세요.
이전 키를 폐기하세요.

키에 만료일을 정하고 그 전에 교체하세요. Sursa는 키가 만료되기 전에 조직 관리자에게 알려요. 만료된 키로 보낸 요청은 401 상태와 api_keys.expired 코드를 반환해요.

키 폐기하기

Administration → API keys에서 키를 폐기하거나 DELETE /v1/api-keys/{key_id}를 호출하세요. 폐기는 모든 API 서버에서 몇 초 안에 적용돼요. 폐기된 키로 보낸 요청은 401 상태와 auth.not_authenticated 코드를 반환해요.

사용자 지정 소스의 키

사용자 지정 소스에는 별도 종류의 키가 있어요. 이 키는 kbsrc_로 시작하고, 그 소스 하나에 문서를 쓰는 일만 할 수 있으며, 아무것도 읽거나 검색할 수 없어요. Zapier 같은 연동 플랫폼에 주기에 가장 안전한 키예요. 소스 페이지의 API keys(API 키) 섹션에서 만들거나 POST /v1/sources/{source_id}/push-keys로 만드세요.

키를 사용할 수 없을 때

API 키는 조직의 요금제에 포함되는 기능이에요. 요금제에 포함되어 있지 않으면 키 생성과 키를 사용한 모든 요청이 403 상태와 api_keys.feature_disabled 코드를 반환해요.