API 키: 만들고, 워크스페이스를 고르고, 폐기하기

따라 하기

1. 1

   1단계 키가 필요한 때를 알기

   API 키는 직접 짠 코드가 씁니다. 업리카 REST API 를 부르는 스크립트, 서버, 자동화 도구 같은 것입니다. 키는 내 계정 대신 움직이므로 비밀번호처럼 보관합니다.

   Claude · ChatGPT 같은 AI 에이전트는 키를 쓰지 않습니다. 「MCP」 화면에서 연결하고 브라우저에서 허용하면 됩니다.

   • AI 에이전트 연결하는 법
2. 2

   2단계 키를 만들고 권한 정하기

   대시보드 사이드바에서 「API 키」 를 열고 「키 발급」 를 누릅니다. 키 이름은 그 키를 둘 곳(서버나 도구 이름)으로 지으면 나중에 키끼리 구분하기 쉽습니다.

   「권한」 에서 「읽기 & 쓰기」 는 발행까지 합니다. 「읽기 전용」 는 조회만 하고, 발행하는 호출은 forbidden_scope 로 돌아옵니다. 코드가 읽기만 한다면 「읽기 전용」 를 고릅니다.

   • API 키
3. 3

   3단계 키가 만질 워크스페이스 고르기

   워크스페이스가 둘 이상이면 창에 「어떤 워크스페이스를 만질 키인가요」 칸이 나옵니다. 「API 키」 화면 위쪽에서 고른 워크스페이스가 처음부터 체크돼 있고, 전체를 보고 있었다면 첫 워크스페이스가 체크돼 있습니다. 이 코드가 다룰 워크스페이스를 하나씩 체크합니다.

   「모든 워크스페이스」 는 지금 있는 워크스페이스와 앞으로 추가하는 워크스페이스까지 전부 만집니다. 체크하면 창이 그렇게 알려 줍니다. 워크스페이스를 골라 만든 키는 그 워크스페이스에만 머물고, 나중에 추가한 워크스페이스는 그 키 밖입니다.

   워크스페이스가 하나면 고를 것이 없고, 키는 그 워크스페이스 하나만 만집니다. 두 번째 워크스페이스를 추가한 뒤에는 그 워크스페이스용 키를 새로 만듭니다.

   만든 뒤에는 키의 워크스페이스나 권한을 바꿀 수 없습니다. 새 키를 만들고 옛 키를 폐기합니다.

   • 워크스페이스 사용법
4. 4

   4단계 창을 닫기 전에 키 복사하기

   이 값은 지금만 보입니다. 우리도 이 값을 저장하지 않습니다. 옆의 복사 단추를 누르세요. 복사하기 전에는 「닫기」 가 눌리지 않습니다.

   브라우저가 복사를 막으면 키 아래에 체크 칸이 나옵니다. 키를 손으로 옮겨 적은 뒤 그 칸을 체크하면 창을 닫을 수 있습니다.

   키는 코드가 비밀값을 읽는 곳(환경변수나 비밀 관리 도구)에 둡니다. 채팅, 공유 문서, 커밋에 붙여넣지 않습니다. 잃어버리면 다시 볼 길이 없으니 새로 만듭니다.

5. 5

   5단계 요청마다 키 보내기

   모든 요청의 Authorization 헤더에 Bearer 라는 말 뒤로 키를 넣습니다. 보낼 헤더는 아래에 있습니다.

   키가 워크스페이스 하나만 만진다면 그것으로 끝입니다. 둘 이상을 만진다면 x-uplika-workspace 헤더에 그 요청이 다룰 워크스페이스의 id 를 같이 보냅니다. 빠뜨리면 요청이 workspace_required 로 돌아오고, 그 키의 워크스페이스 목록과 id 가 함께 오니 거기서 id 를 옮겨 쓰면 됩니다.

   키가 한 일은 「로그」 에서 봅니다. 「경로」 칸에 「API 키」 와 키 이름이 나옵니다. 「API 키」 화면의 「마지막 사용」 칸에는 키마다 마지막으로 쓰인 때가 나옵니다.

   • API 문서의 인증
   • 로그
6. 6

   6단계 안 쓰는 키 폐기하기

   「API 키」 에서 그 키 줄 끝의 메뉴를 열고 「키 폐기」 를 고릅니다. 키 이름을 입력하고 「폐기」 를 누릅니다. 이 키를 쓰는 모든 요청이 즉시 401 로 실패합니다. 되돌릴 수 없습니다.

   새어 나갔을지 모르는 키는 바로 폐기하고, 새 키를 만들어 옛 키가 있던 자리에 넣습니다. 폐기한 키는 목록에 「폐기됨」 로 남습니다.