가이드

빠른 시작

RunAPI 관리 키로 표준 API 키와 가드레일을 생성하고 관리합니다.

플랫폼 관리를 사용하면 계정 관리자가 대시보드를 통하지 않고도 표준 API 키와 가드레일을 생성, 조회, 업데이트 및 취소할 수 있습니다.

관리 키 만들기

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

HTTP

Authorization: Bearer YOUR_MANAGEMENT_KEY

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

표준 API 키 목록 조회

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

SHELL

curl "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

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

키 생성 및 교체

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

SHELL

curl -X POST "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production worker"}'

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

가드레일 적용

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

관리 오류 처리

401 Unauthorized는 자격 증명이 누락되었거나, 형식이 잘못되었거나, 취소되었거나, 유효하지 않음을 의미합니다.
403 Forbidden은 자격 증명 클래스 또는 계정 역할이 해당 작업을 수행할 권한이 없음을 의미합니다.
404 Not Found는 요청한 리소스가 인증된 계정에 표시되지 않음을 의미합니다.
422 Unprocessable Content는 제출된 하나 이상의 값이 리소스 규칙을 위반함을 의미합니다.