Webhook 서명 비밀 키 교체 | ToAPIs Documentation

POST

/api/v1/webhook/rotate-secret

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.

동작

지정 키의 서명 비밀 키를 생성하거나 교체합니다. 수신 측은 이것으로 콜백 서명을 검증합니다. 교체 자체로는 콜백이 활성화되지 않습니다. secret은 이 응답에 한 번만 반환되고 GET으로 재발급되지 않으므로 분실 시 다시 교체하세요.

이전 비밀 키는 교체 후 24시간 동안 검증 과도기로 유효하며 구 슬롯은 하나뿐이라 연속 교체 시 교체됩니다.

삭제되거나 scope 가 있는 Key 는 수정할 수 없습니다. 비활성, 만료, 잔액 소진 모델 Key 도 관리할 수 있습니다. 속도 제한은 키 수명주기 쓰기와 공유되며, 사용자당 분당 최대 10회의 쓰기 요청만 허용됩니다.

JSON 최대 16384 바이트, 본문 읽기 제한 10 초이며 쿼리 매개변수, 알 수 없거나 중복된 JSON 필드를 거부합니다. Api_key_id 를 명시해야 합니다.

인증

Authorizationstring헤더필수

시스템 액세스 토큰 Bearer YOUR_SYSTEM_ACCESS_TOKEN 을 사용하며 본인 계정만 접근할 수 있습니다. 모델 Key 는 허용하지 않습니다. X-User-Id 는 필요 없으며 관리자나 팀 권한으로 범위를 우회할 수 없습니다.

요청 매개변수

api_key_idinteger본문필수

본인 일반 모델 Key 의 양의 정수 ID 이며 sk- 비밀 키나 액세스 토큰이 아닙니다. JSON 에서는 정수만 허용하며 문자열, null, 생략, 쿼리 매개변수는 거부합니다.

api_key_id가 유효하지 않으면 400, 대상 키가 없거나 타인 소유이면 404, mode=off에서의 비밀 키 관리는 409 (code=16016), 레이트 리밋 시 429입니다.

요청 예제

요청 예시

curl --request POST \
  --url 'https://api.toapis.com/api/v1/webhook/rotate-secret' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123}'

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "secret": "0000000000000000000000000000000000000000000000000000000000000000",
    "previous_secret_expires_at": null
  }
}

초기 설정 순서와 서명 검증은 Webhook 설정 조회를 참조하세요.