API 인증#

모든 API 요청에 bearer 자격 증명을 보내세요.

bash

Authorization: Bearer pat_...

bearer 자격 증명은 서버 측에 보관하세요. API 자격 증명이 없거나 유효하지 않아도 요청이 브라우저 쿠키를 대신 사용하지는 않습니다.

개인 액세스 토큰#

PAT는 pat_로 시작합니다. Supernova는 비밀 값을 한 번만 표시하고 해시만 저장합니다. 비밀 값을 잃어버리면 복구할 수 없으므로 새 토큰을 생성하세요.

각 PAT는 사용자 1명과 조직 1개에 속하며, 명시적인 권한 범위 집합과 선택적인 만료일을 기록합니다. 폐기는 다음 요청부터 적용됩니다.

서비스 키는 nsk_로 시작하며 개인이 아닌 조직에 속합니다. 작업, 스크립트, 작성자가 퇴사한 뒤에도 계속 실행되어야 하는 용도에 사용하세요.

bash

Authorization: Bearer nsk_...

조직 관리자는 설정 → 쿼리 액세스에서 키를 만들고 이름을 지정한 다음 비밀 값을 복사합니다. PAT와 마찬가지로 비밀 값은 한 번만 표시되며 해시만 저장됩니다. 키 폐기는 다음 요청부터 적용됩니다.

키는 읽기 전용이며 정확히 query:read와 data:read 권한만 가집니다. 쿼리를 실행하고 카탈로그를 읽을 수 있으며 이 권한을 확장할 수는 없습니다. 키는 권한이 부여된 테이블만 읽습니다. 거부 응답은 쿼리를 참고하세요.

조직에서 테이블 권한을 활성화한 뒤에 키를 사용할 수 있습니다. 이 권한 부여가 키로 읽을 수 있는 테이블을 결정하기 때문입니다. 그 전에는 유효한 키도 403 service_key_permissions_off로 거부됩니다.

OAuth는 PKCE를 사용하는 인가 코드 방식을 따릅니다. 동의 화면에는 조직과 요청된 권한 범위가 표시됩니다. 액세스 토큰에는 공개 API 대상, 허용된 발급자, 유효한 jti, 엔드포인트에 필요한 권한 범위가 있어야 합니다.

토큰의 주체가 호출자 주체가 됩니다. 같은 조직 안에서도 멱등성과 호출자 요청 빈도 제한은 주체별로 구분됩니다.

GET/whoami

인증된 주체, 조직, 역할, 부여된 권한 범위를 반환합니다. 로그인하거나 프로필을 선택한 뒤 호출하여 자격 증명이 어느 테넌트를 대상으로 하는지 확인하세요.

GET/orgs

자격 증명 계약에서 선택을 허용하는 경우 인증된 사용자가 사용할 수 있는 조직을 반환합니다.

유효한 자격 증명이라도 필요한 권한 범위가 없으면 엔드포인트는 403 insufficient_scope로 거부합니다.