감사 내보내기 생성

POST /v1/audit-exports · 권한 audit-exports:write

일치하는 감사 레코드를 서명된 패키지에 기록하는 작업을 큐에 넣습니다. 이 패키지는 KeenAuth를 신뢰하지 않고도 검증할 수 있습니다. 작업은 202 Accepted와 함께 반환됩니다. 감사 내보내기 조회로 작업을 확인하고 감사 내보내기 다운로드로 파일을 가져오십시오.

API 키(비밀 키 또는 제한된 키)만 내보내기를 생성할 수 있습니다. 작업에는 키가 requested_by로 기록됩니다. 환경은 키에서 결정됩니다.

요청

Idempotency-Key는 필수입니다(16~64자, A-Z a-z 0-9 _ -). 같은 키와 같은 본문으로 요청하면 Idempotent-Replayed: true와 함께 첫 번째 작업이 반환됩니다. 같은 키에 다른 본문을 보내면 422 idempotency_key_reuse로 실패합니다. SDK와 CLI가 이 헤더를 자동으로 설정합니다.

필터는 감사 이벤트 목록과 같습니다. 생략한 필드는 필터링에 사용되지 않습니다. 차이점은 다음과 같습니다:

필드	유형	설명
`stream`	string	`admin`(기본값) 또는 `application`.
`from`	RFC 3339	하한(포함). 기본값은 보존 기간의 시작입니다. 92일 제한은 없으며, 패키지에는 최대 5천만 줄(자리 표시자 포함)이 들어갑니다.
`to`	RFC 3339	상한(제외). 기본값은 현재 시각이며, 미래 시각일 수 없습니다.
`action`, `category`, `actor_type`, `actor_id`, `target_type`, `target_id`, `org_id`, `outcome`, `request_id`, `correlation_id`, `agent_only`		목록 필터와 같습니다. 목록의 `client` 필터는 여기서 사용할 수 없으며, `client` 필드를 보내면 `400 unknown_field`로 실패합니다.
`include_ip`	boolean	생성 후 13개월 이내의 레코드에 전체 IP 주소와 사용자 에이전트를 추가합니다. `audit-events:read_ip` 권한도 필요합니다. 기본값은 `false`입니다.

{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}

환경별로 동시에 실행되는 작업은 최대 3개입니다(개발 및 스테이징 환경에서는 1개).

응답

202 Accepted와 status가 queued인 작업이 반환됩니다. filter에는 from과 to의 기본값이 채워진 적용 필터가 표시됩니다. recorded_before는 스냅숏 상한으로, 이 시각 이전에 저장된 레코드만 패키지에 포함됩니다.

{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}

오류

모든 오류는 안정적인 code가 포함된 application/problem+json 본문으로 반환됩니다.

HTTP	`code`	발생 조건
400	`malformed_request`	`Idempotency-Key`가 없거나 형식이 잘못되었거나, 본문이 올바른 JSON이 아닙니다.
400	`unknown_field`	본문에 위에 나열되지 않은 필드가 있습니다.
400	`invalid_filter`	감사 서비스가 필터를 거부했습니다(예: 미래 시각의 `to`).
400	`range_outside_retention`	`from` 또는 `to`가 요금제의 감사 보존 기간 밖에 있습니다.
422	`validation_failed`	필드가 유효하지 않습니다(잘못된 유형, 잘못된 타임스탬프, `from`보다 이전인 `to`, 알 수 없는 열거형 값, 형식이 잘못된 ID, 빈 문자열).
422	`idempotency_key_reuse`	다른 본문과 함께 `Idempotency-Key`를 재사용했습니다.
401	`unauthenticated`	API 키가 없거나 유효하지 않거나 폐기되었습니다.
403	`insufficient_permissions`	키에 `audit-exports:write` 권한이 없거나, `audit-events:read_ip` 없이 `include_ip`를 사용했거나(`required_permissions`에 두 권한이 모두 표시됩니다), 호출자가 API 키가 아닙니다.
429	`rate_limited`	이 환경에서 실행 중인 작업이 너무 많거나 요청 한도를 초과했습니다. `Retry-After`를 준수하십시오.
503	`service_unavailable`	종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

예시

curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'

keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.

개인정보

이 엔드포인트는 개인정보인 감사 이벤트를 다룹니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간 및 삭제 방법을 확인하십시오. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.