API 키 발급
콘솔에서 client_id 와 client_secret 을 발급하고, 그 키가 어떤 환경을 호출할 수 있는지 정리합니다.
발급 순서
- 콘솔 로그인
콘솔에 로그인합니다. 새로 가입하면 키가 하나 자동으로 발급됩니다.
키를 발급하고 재발급하고 폐기하는 일은 조직의 소유자와 관리자만 할 수 있습니다.
- 키 관리 열기
왼쪽 메뉴 키 관리를 엽니다. 가입 직후에는 가입 때 발급된 키의 시크릿이 화면에 한 번 표시됩니다.
사용 중인 키가 없을 때만 키 발급 단추가 보이고, 사용 중인 키가 있으면 재발급로 새 키를 받습니다.
- client_secret 저장
시크릿은 발급 직후 한 번만 표시됩니다. 화면을 벗어나면 다시 볼 수 없으니, 서버의 환경 변수나 비밀 저장소로 그 자리에서 옮깁니다.
- API 호출에 사용
두 값을 인증에서 설명하는 대로 Authorization 헤더에 담습니다.
AI 에이전트가 사용자 대신 가입시키고 키를 받는 길도 있습니다.에이전트가 사용자의 이메일 하나로 계정을 만들면 키가 바로 나오고, 사용자는 나중에 메일의 링크로 계정을 넘겨받습니다. 그 절차는 auth.md에 있습니다.읽는 쪽이 에이전트라 영어로 적힌 문서입니다.
계정을 넘겨받은 사람이 콘솔 키 관리에서 계속 쓰기를 누르기 전까지는 그 키로 부르면 403 AUTHZ_FORBIDDEN(reason 은 credential_takeover_pending)이 옵니다.키를 다시 발급하지 않아도 그 버튼을 누르면 같은 키로 이어집니다 - 오류 코드.
발급되는 값
| 항목 | 형식 | 설명 |
|---|---|---|
| client_id | cli_ + 26자 (총 30자) | 키를 가리키는 공개 식별자입니다. 설정 파일이나 로그에 남아도 됩니다. |
| client_secret | csk_ + 48자 (총 52자) | 비밀 값입니다. 발급 직후 한 번만 표시되며 다시 조회할 수 없습니다. |
키가 쓸 수 있는 환경
키마다 호출할 수 있는 환경이 정해져 있습니다. 그 목록에 없는 환경으로 호출하면 403 POLICY_ENV_FORBIDDEN 이 돌아옵니다.
- STEP 01발급 직후
데모가 이미 승인된 조직이면 발급되는 키에 real_test 가 붙습니다.
- STEP 02데모 승인
가입하면 데모가 자동으로 승인됩니다. 승인 전인 조직은 콘솔에서 데모를 신청하고 승인되면 real_test 가 더해집니다.
- STEP 03요금제 변경
요금제를 시작하면 production 이 자동으로 더해집니다.
요금제가 해지되거나 만료되면 production 은 키에서 다시 빠집니다. 데모 신청 방법은 환경에 있습니다.
키를 다시 발급하거나 폐기할 때
| 상황 | 콘솔에서 할 일 | 결과 |
|---|---|---|
| 시크릿을 잃어버렸을 때 | 재발급 | 기존 키를 폐기하고 새 client_id·client_secret 을 발급합니다. 예전 키를 쓰던 코드는 함께 바꿔야 합니다. |
| 키가 유출됐을 때 | 폐기 | 그 키의 호출이 곧바로 막힙니다. 폐기된 키로 호출하면 401 AUTH_CREDENTIAL_INVALID 입니다. |
client_secret 을 저장소·프런트엔드 코드·로그에 남기지 마세요. 서버에서만 읽는 환경 변수나 비밀 저장소에 둡니다.
여러 고객사의 자격증명을 키 하나로 연동하는 연동사·플랫폼이라면 콘솔 멀티계정 연동에서 신청합니다. 심사가 끝나면 전용 키를 받고, 그 키로는 API 로도 자격증명을 등록할 수 있습니다.