매뉴얼

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

직접 만든 코드가 쓸 API 키를 만들고, 그 키가 다룰 워크스페이스를 고르고, 요청마다 키를 보내고, 안 쓰게 되면 폐기해요. AI 에이전트에는 키가 필요 없어요.

화면 기준일: 2026년 11월 4일

API 키를 만들고, 안전하게 보관하고, 요청에 넣고, 폐기하는 순서예요.

따라 하기

키가 필요한 때를 알기

API 키는 직접 만든 코드가 써요. 포샌디 REST API를 부르는 스크립트, 서버, 자동화 도구 같은 것이에요. 키는 내 계정 대신 움직이니까 비밀번호처럼 보관해요.

Claude, ChatGPT 같은 AI 에이전트는 키를 쓰지 않아요. 'MCP' 화면에서 연결하고 브라우저에서 허용하면 돼요. 방법은 AI 연결하기에 있어요.
키를 만들고 권한 정하기

대시보드 사이드바에서 'API 키'를 열고 '키 발급'을 눌러요. 키 이름은 그 키를 둘 곳(서버나 도구 이름)으로 지어요. 그러면 나중에 키를 구분하기 쉬워요.

'권한'에서 '읽기 & 쓰기'는 글 올리기까지 할 수 있어요. '읽기 전용'은 조회만 해요. 읽기 전용 키로 글을 올리면 forbidden_scope로 돌아와요. 코드가 읽기만 한다면 '읽기 전용'을 골라요.
키가 다룰 워크스페이스 고르기

워크스페이스가 둘 이상이면 창에 '어떤 워크스페이스를 만질 키인가요' 칸이 나와요. 'API 키' 화면 위쪽에서 고른 워크스페이스가 미리 체크돼 있어요. 전체를 보고 있었다면 첫 번째 워크스페이스가 체크돼 있어요. 이 코드가 다룰 워크스페이스를 하나씩 체크해요.

'모든 워크스페이스'를 체크하면 지금 있는 워크스페이스와 앞으로 만들 워크스페이스까지 모두 다뤄요. 체크하면 창에 그렇게 안내가 나와요. 워크스페이스를 골라서 만든 키는 그 워크스페이스만 다뤄요. 나중에 만든 워크스페이스는 그 키로 다룰 수 없어요.

워크스페이스가 하나면 고를 게 없어요. 키는 그 워크스페이스 하나만 다뤄요. 두 번째 워크스페이스를 만든 다음에는 그 워크스페이스용 키를 새로 만들어요.

만든 다음에는 키의 워크스페이스나 권한을 바꿀 수 없어요. 바꾸려면 새 키를 만들고 옛 키를 폐기해요. 워크스페이스는 워크스페이스 사용법에 있어요.
창을 닫기 전에 키 복사하기

키 값은 이 창에서만 보여요. 포샌디도 이 값을 저장하지 않아요. 옆의 복사 버튼을 눌러요. 복사하기 전에는 '닫기'가 눌리지 않아요.

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

키는 코드가 비밀값을 읽는 곳(환경변수나 비밀 관리 도구)에 둬요. 채팅, 공유 문서, 커밋에는 붙여넣지 않아요. 잃어버리면 다시 볼 방법이 없어요. 그때는 새로 만들어요.
요청마다 키 보내기

모든 요청의 Authorization 헤더에 Bearer 다음 키를 넣어요. 보낼 헤더는 아래에 있어요.

키가 워크스페이스 하나만 다룬다면 이걸로 끝이에요. 둘 이상을 다룬다면 x-posendy-workspace 헤더에 그 요청이 다룰 워크스페이스 id를 함께 보내요. 빠뜨리면 요청이 workspace_required로 돌아와요. 이때 그 키의 워크스페이스 목록과 id가 같이 오니까, 거기서 id를 복사해 쓰면 돼요.

키로 한 일은 '로그'에서 확인해요. '경로' 칸에 'API 키'와 키 이름이 나와요. 'API 키' 화면의 '마지막 사용' 칸에는 키마다 마지막으로 쓴 때가 나와요. 인증 방법은 API 문서의 인증에 있어요.
안 쓰는 키 폐기하기

'API 키' 화면에서 그 키 줄 끝의 메뉴를 열고 '키 폐기'를 골라요. 키 이름을 입력하고 '폐기'를 눌러요. 이 키를 쓰는 모든 요청이 바로 401로 실패해요. 되돌릴 수 없어요.

밖으로 새어 나갔을 수 있는 키는 바로 폐기해요. 그리고 새 키를 만들어 옛 키가 있던 자리에 넣어요. 폐기한 키는 목록에 '폐기됨'으로 남아요.

보낼 헤더

Authorization: Bearer <내 키>
x-posendy-workspace: <워크스페이스 id>

키는 psd_로 시작해요.

만날 수 있는 오류

코드	뜻	할 일
`invalid_api_key`	키가 없거나, 잘못 적혔거나, 일부가 잘려서 들어왔어요.	키 전체를 다시 복사하거나 새 키를 만들어요.
`api_key_revoked`	대시보드에서 폐기한 키예요.	새 키를 만들어 바꿔 넣어요.
`forbidden_scope`	읽기 전용 키로 글을 올리거나 무언가를 바꾸려고 했어요.	읽기와 쓰기를 다 할 수 있는 키를 만들어요.
`workspace_required`	키가 워크스페이스 둘 이상을 다루는데 요청에 어느 것인지 없거나, 키가 다루지 않는 워크스페이스를 가리켰어요.	오류에 같이 온 목록에서 워크스페이스 id를 골라 보내요.

이어 읽기

막혔을 때

AI가 workspace_required를 받아요.

이런 경우의 답은 안 될 때에 모아 뒀어요.

내 계정으로 해 보기

채널을 연결하고, 쓰던 AI에 포샌디를 연결하고, 올려 달라고 말하면 돼요. 카드 없이 시작해요. 가입하기