관리 API 인증 및 마이그레이션
rc.44 세션, 관리 PAT, 모델 API 키, 보안 증명의 차이
버전 및 API 주소
이 페이지는 2026-10-15에 확인한 new-api v1.0.0-rc.44 기준입니다. 관리 요청은 https://api.beeaicloud.com으로 보냅니다. 문서 도메인은 API 주소가 아닙니다. 원본 /api/, BeeBridge /management-api/, /integration-api/는 서로 다른 계약, 세션, 오류 형식을 사용합니다.
서로 다른 세 가지 자격 증명
세션 access_token은 비밀번호 또는 OAuth 로그인으로 발급되는 단기 Bearer 자격 증명으로 세션과 PAT 관리에 사용합니다. 관리 PAT는 nap_로 시작하고 선택한 관리 권한만 가지며 PAT 자체를 만들거나 관리할 수 없습니다. 모델 API 키는 /v1/ 등의 추론 요청용입니다. 같은 Authorization 헤더를 사용해도 서로 대체할 수 없습니다. New-Api-User로 다른 계정을 선택할 수 없으며 서버가 자격 증명으로 신원을 결정합니다.
로그인과 비밀번호 암호화
먼저 GET /api/user/login/encryption-key를 호출합니다. enabled=true이면 로그인과 비밀번호 검증에 password_encrypted와 encryption_key_id를 전송하고 반환된 kid를 사용합니다. Base64 RSA-OAEP/SHA-256 암호문을 지원합니다. 긴 비밀번호의 v2는 새 32바이트 AES 키를 password-v2 라벨의 RSA-OAEP로 감싸고, AES-256-GCM에 12바이트 nonce와 AAD password-v2:{kid}를 사용하며 암호문 끝에 16바이트 태그를 붙입니다. 형식은 v2.{wrappedKeyBase64}.{nonceBase64}.{ciphertextAndTagBase64}입니다. 암호화가 꺼진 경우에만 HTTPS로 평문 password를 보냅니다.
POST /api/user/login 후 data.require_verification을 확인하세요. true이면 data.methods에 따라 flow_token으로 /api/user/login/verify 또는 전용 Passkey 흐름을 완료한 뒤 최종 data.access_token을 사용합니다. 로그인 추가 인증과 /api/verify의 작업 증명은 다릅니다. 갱신은 new_api_refresh 쿠키와 POST /api/user/auth/refresh, 로그아웃은 POST /api/user/auth/logout입니다. 쿠키 요청의 Origin 검증을 위조해 우회하지 마세요.
작업 추가 검증
GET /api/verify/methods?scope=access_token.generate에서 available=true인 방법을 선택합니다. POST /api/verify에 method, 작업 scope, 엄격한 context를 보냅니다. data.proof_token은 같은 신원과 세션 및 같은 작업 내용으로 X-Security-Proof에 넣어 한 번만 사용합니다. Passkey와 OAuth는 전용 대화형 흐름이 필요하며 method만 바꿔서는 완료되지 않습니다.
관리 PAT와 권한
로그인 세션으로 /api/user/access_tokens/catalog를 조회해 필요한 권한을 선택하세요. profile:read는 본인 정보 조회만 허용하며 키 관리, 전체 사용량 조회, 지갑 작업 권한을 의미하지 않습니다. /api/user/access_tokens/scopes는 이름 사전으로 현재 부여 가능한 권한 목록이 아닙니다. 계정 상태, 역할, 현재 인가도 PAT 접근을 제한합니다.
실패와 재시도
HTTP 상태와 success를 모두 확인하세요. 코드는 code 또는 data.code에 있으며 HTTP 200이어도 비즈니스 실패일 수 있습니다. 400 SECURITY_CONTEXT_INVALID는 context, 401은 자격 증명, 403은 세션 요구 사항과 권한을 확인하세요. 429이면 연속 재시도를 멈추고 대기하세요. 생성·취소·변경 응답을 잃으면 다시 보내기 전에 상태를 확인합니다. 로그에는 정제된 코드, 시각, 요청 ID만 기록하고 비밀 값은 기록하지 마세요.
기존 방식 마이그레이션
기존 GET/POST /api/user/token은 새 PAT 발급에 사용하지 않으며 POST /api/user/access_tokens로 전환합니다. GET /api/user/logout은 POST /api/user/auth/logout, GET /api/verify/status는 scope를 지정한 /api/verify/methods, GET /api/oauth/state는 POST /api/oauth/state로 대체합니다. 증명은 검증 응답에서 받습니다. 전환 기간에 기존 PAT가 동작해도 이전 발급 방식이 유지되는 것은 아닙니다. 기한은 목록의 data.legacy.retire_at에서 확인하세요. 현재 운영 진입점에서는 원본 공개 회원가입이 닫혀 있습니다.
이 문서가 도움이 되었나요?