빠른 시작

인증 가이드에 따라 로그인한 후 관리 키 페이지를 열고 관리 키를 생성하세요. 표준 애플리케이션 키와 별도로 보관하세요. 플랫폼 관리 엔드포인트에만 Bearer 토큰으로 전송하세요.

표준 API 키는 키 또는 가드레일 관리 엔드포인트를 호출할 수 없습니다. 유효한 관리 키라도 소유자가 필요한 계정 역할을 더 이상 보유하지 않는 경우 403 Forbidden이 반환될 수 있습니다.

관리 키 계정에서 볼 수 있는 키를 조회하려면 GET /api/v1/keys를 사용하세요:

나중의 조회, 업데이트, 취소, 또는 가드레일 할당 요청에는 반환된 공개 식별자를 사용하세요. 키 이름이나 마스킹된 토큰으로 접근 권한을 유추하지 마세요.

POST /api/v1/keys로 애플리케이션 키를 만듭니다. 전체 시크릿은 만들기 응답에서만 반환되므로 해당 응답을 삭제하기 전에 시크릿 관리자에 저장하십시오. 교체 시에는 대체 키를 만들고 애플리케이션에 배포하여 트래픽을 확인한 후 이전 키를 폐기하십시오.

credit_limit_windows는 1h, 1d, 7d 롤링 지출 한도의 임의 조합을 허용합니다. 설정된 윈도우 중 하나라도 소진되면, 해당 키를 사용하는 호출은 사용량이 해당 윈도우를 벗어날 때까지 429 Too Many Requests를 반환합니다. 키를 업데이트할 때 빈 객체를 전송하면 모든 롤링 한도가 초기화됩니다.

생성 요청에서 모든 지출 한도 필드와 guardrail_id를 생략하면 새 키는 워크스페이스의 거버넌스 기본값을 사용합니다. 명시적 한도, 이동 시간 창 또는 가드레일을 지정하면 해당 기본 선택을 대체합니다. 네이티브 한도를 무제한으로 생성하려면 credit_limit_cents: null을 보내세요. 초기화 주기 없이 금액을 지정하면 평생 한도로 유지됩니다. 업데이트는 워크스페이스 기본값을 다시 적용하지 않으며, 기본값을 변경해도 기존 키는 변경되지 않습니다.

생성과 수정은 전체 key:value 문자열 배열인 tags를 받습니다. 목록, 조회, 생성, 수정 응답은 전체 배열을 반환합니다. PATCH는 배열을 교체하며 tags를 생략하면 유지합니다. 키는 1–32자, 값은 1–64자이며 콜론은 정확히 하나이고 공백 문자는 허용되지 않습니다. 기본 태그를 포함해 서로 다른 태그를 최대 20개 지정할 수 있습니다. 잘못된 형식이나 충돌하는 기본 태그는 태그 검증 오류와 함께 422를 반환하며, 배열이 아니거나 문자열이 아닌 요소가 있으면 400을 반환합니다.

용도 태그는 usage:developer 또는 usage:service 중 정확히 하나가 필요합니다. Management API 생성에서 용도를 지정하지 않으면 tags: []인 경우에도 usage:service를 추가합니다. Dashboard 생성 및 용도 없는 태그 수정은 usage:developer를 사용합니다. 기존 키는 Developer로 마이그레이션됩니다. 환경은 선택 사항이며 env:production, env:staging, env:dev 중 최대 하나만 허용합니다(env:prod는 허용하지 않음).

Dashboard 생성 및 수정에서는 용도와 환경 빠른 선택, 사용자 정의 태그, 현재 워크스페이스의 삭제되지 않은 표준 키에서 가져온 제안을 제공합니다. 목록에는 값이 표시되고 마우스를 올리면 전체 태그가 표시됩니다. 태그는 키 소유권, 공개 범위 또는 권한을 변경하지 않습니다. 태그를 통해 키를 공유 태그 예산에 연결할 수 있습니다.

워크스페이스 관리자는 Team의 멤버 예산 양식에서 멤버의 필수 태그를 설정합니다. 필수 태그는 team:growth와 같이 대소문자를 구분하는 사용자 정의 태그입니다. usage: 및 env: 네임스페이스는 예약되어 있습니다. 멤버는 최대 19개의 필수 태그를 가질 수 있으며 각 키의 전체 태그 수는 여전히 20개로 제한됩니다.

새 표준 키에는 해당 워크스페이스에서 소유자에게 설정된 필수 태그가 자동으로 포함됩니다. 생성 시 제출된 태그와 필수 태그를 합친 후 유효성을 검사합니다. 예를 들어 멤버에게 team:growth가 필수인 경우, Management API 생성 요청에 tags: ["project:chatbot"]를 보내면 project:chatbot, team:growth 및 기본 usage:service가 반환됩니다.

tags를 지정하는 PATCH는 모든 필수 태그를 유지해야 합니다. 필수 태그를 제거하면 호출자가 관리자여도 누락된 태그를 명시하는 유효성 검사 오류와 함께 422가 반환됩니다. tags를 생략하면 키의 태그가 유지됩니다. 멤버는 일반 태그를 계속 추가하거나 제거할 수 있습니다.

필수 태그를 제거하려면 관리자가 Team에서 멤버 설정을 변경해야 합니다. 설정을 저장하면 해당 멤버의 모든 기존 표준 키에 새 필수 태그가 추가되고 해제된 필수 태그가 제거됩니다. 다른 태그는 유지됩니다. 비활성화되거나 만료된 키도 포함되지만 삭제된 키는 제외됩니다. 키 하나라도 최종 태그 집합을 수용할 수 없으면 전체 저장이 실패하고 양식에 수정할 키가 표시됩니다.

태그 예산은 각 키의 현재 태그를 사용합니다. 필수 태그를 변경하면 현재 기간에 이미 발생한 지출의 예산 귀속도 변경됩니다. 필수 태그를 추가하는 즉시 해당 태그의 예산이 소진될 수 있습니다. 기존 멤버의 필수 태그는 처음에 비어 있으며, 관리자가 설정을 저장할 때까지 키는 변경되지 않습니다.

Guardrails는 모델, 공급자 및 지출 제어를 위한 재사용 가능한 계정 정책입니다. /api/v1/guardrails를 통해 정책을 관리한 다음 /api/v1/guardrail_assignments를 사용하여 연결하거나 제거하세요. Guardrail 없이 자동으로 계속하는 대신 거부된 할당을 정책 또는 소유권 오류로 처리하세요.

양수 한도의 block 모드 가드레일을 만든 뒤 guardrail_id와 dept:ml 같은 대소문자 구분 tag를 할당하세요. 대상은 api_token_id, account_user_id, tag 중 정확히 하나입니다. 태그 예산에는 관리자 권한이 필요합니다. 비활성 예산은 한도를 적용하지 않습니다. 관리 요청은 예산을 소비하지 않습니다.

예산은 표준 키의 현재 태그를 집계하며 삭제, 비활성, 만료된 키의 지출도 포함합니다. 태그를 추가하거나 제거하면 해당 키의 현재 기간 지출이 이동합니다. 예산을 만들거나 다시 만들어도 지출은 초기화되지 않습니다. 키 수에는 삭제된 키가 포함되지 않습니다. 일치하는 모든 예산이 요청을 허용해야 하며, 거부 시 403과 태그 이름을 반환합니다.

credit_limit_reset_interval이 null이면 평생 한도입니다. 다른 기간은 UTC를 사용합니다. 알림 임계값 기본값은 80이며 1~100을 허용합니다. 가드레일을 직접 수정하면 모든 할당에 적용됩니다. 대시보드에서 태그 예산을 수정할 때는 먼저 정책을 복사합니다.

요청 수락 시 예약 금액을 확인합니다. 정산 금액이 예약 금액을 초과해 사용률이 100%를 넘고 이후 유료 요청이 차단될 수 있습니다. 로그는 로그 생성 시각을, 대기 중인 작업과 배치는 각각의 생성 시각을 사용합니다. 이전 기간에 수락한 작업이 이후 기간에 정산될 수 있습니다.