조직 API 키로 에이전트 만들기

조직 API 키는 에이전트 토큰과 다른 것입니다. 조직 API 키(atk_org_…)는 에이전트를 만들고 읽기만 하고, 메일을 보내거나 읽지 못합니다. 에이전트 토큰(atk_agent_…)은 조직 API로 쓸 수 없습니다.

시작하기 전에#

• 역할이 소유자여야 합니다. 조직 API 키는 소유자만 보고 관리합니다.

키 발급하기#

1. 새 키 열기#

   설정 › API 키에서 새 키를 누릅니다.

2. 이름·권한·만료 고르기#

   이름(60자까지), 권한(에이전트 읽기 agents:read, 에이전트 만들기 agents:create 중 하나 이상), 만료를 고릅니다.

3. 저장하고 닫기#

   발급하기를 누르면 키가 한 번만 보입니다. CI의 비밀 저장소에 바로 넣고, 확인란을 누른 뒤 창을 닫습니다.

조직당 활성 키 수는 요금제가 정합니다(최대 5개).

API 쓰기#

기본 URL은 콘솔 주소입니다.

https://console.atmark.ai/org-api/v1

curl -sS https://console.atmark.ai/org-api/v1/agents \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Help desk agent", "localPart": "desk"}'

만들기 응답(201)은 {agent, token}입니다. 새 에이전트의 첫 토큰은 이 응답에 한 번만 옵니다. 바로 비밀 저장소에 넣으세요. 만들기는 콘솔과 같은 규칙을 따릅니다. 주소 규칙, 에이전트 수 한도, 검토 중 상한이 똑같이 걸립니다.

• 브라우저에서 부르면 403 origin_forbidden입니다. 서버나 CI에서 부릅니다.
• 요청이 너무 잦으면 429 rate_limited입니다.
• 키가 없거나 틀리면 401 unauthenticated입니다.

교체와 폐기#

키 행의 동작 메뉴에서 고릅니다.

• 교체: 같은 이름·권한의 새 키를 발급하고 지금 키는 바로 폐기합니다. CI의 비밀 값을 새 키로 바꿔야 합니다.
• 폐기: 이 키를 쓰는 CI는 바로 401을 받습니다. 이 키로 만든 에이전트는 그대로입니다. 되돌릴 수 없습니다.