서비스 계정 및 키

CI와 자동화를 위한 서비스 계정과 그 키, 정책, 위임, 감사.

이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).

작업

서비스 계정 목록

GET HEAD /api/v1/service-accounts

액세스: 서비스 관리 권한 service-account.read · 재시도: 반복해도 안전함(읽기)

호출자가 볼 수 있는 서비스 계정을 ID 순으로 페이지당 50개 나열하며, 이름, 활성화 플래그, revision, 정책 bindings, 생성 시각이 있고 after에 next 값을 넣어 이어서 조회합니다. 부트스트랩 키는 모든 계정을 보고, 위임받은 키는 위임에 service-account.read가 포함된 대상만 봅니다. 그 권한이 없으면 거부되지 않고 빈 목록이 반환됩니다.

매개 변수

이름	위치	형식	필수	규칙
`after`	쿼리	string (uuid)	아니요	—

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 50개 이하
`items[].id`	string (uuid)	예	—
`items[].name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`items[].enabled`	boolean	예	—
`items[].revision`	integer	예	1–2147483647
`items[].bindings`	object 배열	예	요소 64개 이하
`items[].bindings[].resource`	object	예	—
`items[].bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`items[].createdAt`	string (date-time)	예	—
`next`	string (uuid)	예	null일 수 있음

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

서비스 계정 생성

POST /api/v1/service-accounts

액세스: 부트스트랩 키(설치 복구 키) · 재시도: 자동으로 반복하지 않음

CI나 애플리케이션용 머신 ID를 name(문자, 숫자, _.- 3–64자)과 정책 bindings로 만듭니다. 바인딩은 리포지토리마다 그 키가 사용할 수 있는 정확한 액션(예: upload.create, content.read)입니다. 계정과 함께 201로 응답하며, 이후 issueServiceKey로 키를 발급합니다. 이미 사용 중인 이름은 409 already_exists입니다.

요청 본문 (application/json)

필드	형식	필수	규칙
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답 201

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—

응답: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/service-accounts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

서비스 계정 조회

GET HEAD /api/v1/service-accounts/{id}

액세스: 서비스 관리 권한 service-account.read · 재시도: 반복해도 안전함(읽기)

계정의 이름, 활성화 플래그, revision, 정책 바인딩, 생성 시각을 반환합니다. 위임받은 키가 자신에게 배정되지 않은 계정을 조회하면 404이고, 배정된 계정에서 필요한 액션이 없으면 403입니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

응답 200

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

서비스 계정 활성화 또는 비활성화

PATCH /api/v1/service-accounts/{id}

액세스: 서비스 관리 권한 service-account.manage · 재시도: 예상 리비전으로만 반복(compare-and-swap)

enabled를 설정하며, expectedRevision은 현재 리비전이어야 하고 그렇지 않으면 409 revision_mismatch입니다. 여기서 바뀌는 것은 이 플래그뿐입니다(이름은 변경할 수 없음). 비활성화하면 다음 요청부터 계정의 모든 키가 차단되고, 활성화하면 만료되거나 폐기되지 않은 키가 복원됩니다. 위임받은 키는 현재 정책 전체가 자신의 상한 안에 있을 때만 이 작업을 할 수 있습니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

요청 본문 (application/json)

필드	형식	필수	규칙
`expectedRevision`	integer	예	1–2147483646
`enabled`	boolean	예	—

응답 200

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X PATCH "$ARKVORY_URL/api/v1/service-accounts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1,"enabled":false}'

서비스 계정 정책 조회

GET HEAD /api/v1/service-accounts/{id}/policy

액세스: 서비스 관리 권한 policy.read · 재시도: 반복해도 안전함(읽기)

policy.read 권한을 가진 호출자에게, getServiceAccount처럼 계정을 정책 bindings 및 revision과 함께 반환합니다. 키의 유효 권한은 이 정책과 키 자체의 바인딩의 교집합이며, 리포지토리와 액션별로 계산됩니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

응답 200

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

서비스 계정 정책 교체

PUT /api/v1/service-accounts/{id}/policy

액세스: 서비스 관리 권한 policy.manage · 재시도: 예상 리비전으로만 반복(compare-and-swap)

계정의 bindings(각각 리포지토리와 정확한 액션으로 이루어진 항목, 최대 64개)를 교체하며, expectedRevision은 현재 리비전이어야 하고 그렇지 않으면 409 revision_mismatch입니다. 모든 키는 다음 요청부터 변경을 따릅니다. 범위를 좁히면 즉시 적용되고, 넓혀도 키 자신의 바인딩을 넘지는 않습니다. 위임받은 키는 현재 정책과 새 정책이 모두 자신의 상한 안에 있어야 합니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

요청 본문 (application/json)

필드	형식	필수	규칙
`expectedRevision`	integer	예	1–2147483646
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답 200

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X PUT "$ARKVORY_URL/api/v1/service-accounts/$ID/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1,"bindings":[]}'

서비스 계정의 키 목록

GET HEAD /api/v1/service-accounts/{id}/keys

액세스: 서비스 관리 권한 credential.read · 재시도: 반복해도 안전함(읽기)

계정의 키 메타데이터를 ID 순으로 페이지당 50개 나열하며, 이름, state(pending, active, revoked), 바인딩, 생성, 만료, 활성화 기한, 교체 전 키가 있고 비밀 값이나 해시는 절대 포함하지 않습니다. after에 next 값을 넣어 이어서 조회합니다. 만료되어도 state는 바뀌지 않으므로 expiresAt을 현재 시각과 비교합니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`after`	쿼리	string (uuid)	아니요	—

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 50개 이하
`items[].id`	string (uuid)	예	—
`items[].accountId`	string (uuid)	예	—
`items[].name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`items[].state`	string	예	`pending`, `active`, `revoked` 중 하나
`items[].bindings`	object 배열	예	요소 64개 이하
`items[].bindings[].resource`	object	예	—
`items[].bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`items[].createdAt`	string (date-time)	예	—
`items[].expiresAt`	string (date-time)	예	—
`items[].activationExpiresAt`	string (date-time)	예	—
`items[].rotatedFrom`	string (uuid)	예	null일 수 있음
`next`	string (uuid)	예	null일 수 있음

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/keys" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

서비스 계정의 키 발급

POST /api/v1/service-accounts/{id}/keys

액세스: 서비스 관리 권한 credential.manage · 재시도: 같은 Idempotency-Key로 반복하면 안전함

name, bindings(계정 정책에서도 허용되는 범위에서만 유효), 선택 사항인 expiresAt(UTC, 기본 90일, 최대 365일이며 위임받은 키가 발급하는 경우 자신의 키 만료 이후로 설정할 수 없음)로 대기 상태의 키를 발급합니다. 첫 응답은 key와 한 번만 표시되는 secret을 담은 201이고, 같은 Idempotency-Key와 본문으로 반복하면 메타데이터만 담은 200, 본문이 다르면 409입니다. 키 소유자는 15분 안에 비밀 값으로 activateServiceKey를 호출해야 하며, 비밀 값을 잃었다면 키를 폐기하고 새 Idempotency-Key로 새 키를 발급합니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`Idempotency-Key`	헤더	string	예	128자 이하

요청 본문 (application/json)

필드	형식	필수	규칙
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`expiresAt`	string (date-time)	아니요	—

응답 200

필드	형식	필수	규칙
`key`	object	예	—
`key.id`	string (uuid)	예	—
`key.accountId`	string (uuid)	예	—
`key.name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`key.state`	string	예	`pending`, `active`, `revoked` 중 하나
`key.bindings`	object 배열	예	요소 64개 이하
`key.bindings[].resource`	object	예	—
`key.bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`key.createdAt`	string (date-time)	예	—
`key.expiresAt`	string (date-time)	예	—
`key.activationExpiresAt`	string (date-time)	예	—
`key.rotatedFrom`	string (uuid)	예	null일 수 있음
`secret`	string	아니요	—

응답: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/service-accounts/$ID/keys" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

서비스 계정 감사 기록 조회

GET HEAD /api/v1/service-accounts/{id}/audit

액세스: 서비스 관리 권한 service-audit.read · 재시도: 반복해도 안전함(읽기)

순번 after(기본 0) 이후의 계정 이벤트를 오래된 순으로 최대 100개 반환합니다. 이벤트는 계정, 정책, 키 변경(발급, 교체, 활성화, 폐기 등)이며 각각 행위자, 작업, 키, 시각이 있습니다. 이어서 읽으려면 마지막 sequence를 after로 전달하며 next 필드는 없습니다. 서버 전체에서 최신 100,000개 이벤트만 보관됩니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`after`	쿼리	string	아니요	10진수 숫자로 쓴 정수이며 문자열로 전송

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 100개 이하
`items[].sequence`	string	예	—
`items[].actor`	string	예	—
`items[].action`	string	예	—
`items[].accountId`	string (uuid)	예	—
`items[].keyId`	string (uuid)	예	null일 수 있음
`items[].occurredAt`	string (date-time)	예	—

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/service-accounts/$ID/audit" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

키 조회

GET HEAD /api/v1/api-keys/{id}

액세스: 서비스 관리 권한 credential.read · 재시도: 반복해도 안전함(읽기)

관리형 키 하나의 메타데이터, 즉 계정, 이름, 상태, 바인딩, 생성, 만료, 활성화 기한, 교체 전 키를 반환하며 비밀 값이나 해시는 절대 포함하지 않습니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

응답 200

필드	형식	필수	규칙
`id`	string (uuid)	예	—
`accountId`	string (uuid)	예	—
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`state`	string	예	`pending`, `active`, `revoked` 중 하나
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`createdAt`	string (date-time)	예	—
`expiresAt`	string (date-time)	예	—
`activationExpiresAt`	string (date-time)	예	—
`rotatedFrom`	string (uuid)	예	null일 수 있음

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/api-keys/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

키 교체

POST /api/v1/api-keys/{id}/rotate

액세스: 서비스 관리 권한 credential.manage · 재시도: 같은 Idempotency-Key로 반복하면 안전함

키 id와 같은 계정에 대해 같거나 더 좁은 bindings를 가진 대기 상태의 후속 키를 발급하며, 응답은 issueServiceKey와 같습니다. 일회성 secret을 담은 201이고, 같은 Idempotency-Key로 반복하면 메타데이터만 담은 200입니다. 후속 키가 활성화되면 이전 키는 최대 24시간 더 유효합니다. 새 키가 동작하는 것을 확인한 뒤, 이전 키로 시작한 작업이 끝난 다음에 이전 키를 직접 폐기합니다. 운영자 키가 가진 위임은 후속 키로 복사되지 않습니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`Idempotency-Key`	헤더	string	예	128자 이하

요청 본문 (application/json)

필드	형식	필수	규칙
`name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`bindings`	object 배열	예	요소 64개 이하
`bindings[].resource`	object	예	—
`bindings[].resource.kind`	string	예	`repository` 중 하나
`bindings[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`expiresAt`	string (date-time)	아니요	—

응답 200

필드	형식	필수	규칙
`key`	object	예	—
`key.id`	string (uuid)	예	—
`key.accountId`	string (uuid)	예	—
`key.name`	string	예	`^[a-zA-Z0-9_.-]{3,64}$` 패턴과 일치
`key.state`	string	예	`pending`, `active`, `revoked` 중 하나
`key.bindings`	object 배열	예	요소 64개 이하
`key.bindings[].resource`	object	예	—
`key.bindings[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나
`key.createdAt`	string (date-time)	예	—
`key.expiresAt`	string (date-time)	예	—
`key.activationExpiresAt`	string (date-time)	예	—
`key.rotatedFrom`	string (uuid)	예	null일 수 있음
`secret`	string	아니요	—

응답: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/api-keys/$ID/rotate" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","bindings":[]}'

키 폐기

POST /api/v1/api-keys/{id}/revoke

액세스: 서비스 관리 권한 credential.manage · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄

키를 영구히 폐기하며, 다음 요청부터 실패하지만 이미 진행 중인 다운로드는 끊기지 않습니다. 반복해도 204로 성공합니다. 폐기된 운영자 키가 발급해 이미 활성화된 키는 계속 유효하므로 별도로 폐기해야 합니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

응답: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/api-keys/$ID/revoke" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

키 활성화

POST /api/v1/auth/activate-key

액세스: 발급된 키(활성화 전 또는 후) · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄

새로 발급된 키를 소유자가 받았음을 증명합니다. 발급 후 15분 안에 그 키를 Authorization: Bearer로 사용해 호출하면 키가 활성 상태가 됩니다(204). 반복해도 안전하며 만료 시각은 연장되지 않습니다. 교체된 키를 활성화하면 그 키가 대체하는 이전 키의 남은 수명이 최대 24시간으로 줄어듭니다.

응답: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/auth/activate-key" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

키의 위임 목록

GET HEAD /api/v1/api-keys/{id}/delegations

액세스: 부트스트랩 키 또는 해당 키 자체 · 재시도: 반복해도 안전함(읽기)

운영자 키 id가 가진 위임을 비활성화된 것을 포함해 최대 64개 반환합니다. 대상 계정마다 revision, enabled 여부, 관리 actions(예: credential.manage), 넘겨줄 수 있는 리포지토리 바인딩의 ceiling이 있습니다. 위임받은 키는 여기서 자신의 위임을 읽을 수 있으며(키 ID는 getOwnPermissions의 credentialId), 다른 키의 목록은 403입니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 64개 이하
`items[].keyId`	string (uuid)	예	—
`items[].targetAccountId`	string (uuid)	예	—
`items[].enabled`	boolean	예	—
`items[].revision`	integer	예	1–2147483647
`items[].actions`	string 배열	예	요소 7개 이하; 중복 항목 없음; 각 요소: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read` 중 하나
`items[].ceiling`	object 배열	예	요소 16개 이하
`items[].ceiling[].resource`	object	예	—
`items[].ceiling[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/api-keys/$ID/delegations" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

서비스 계정 관리 위임

PUT /api/v1/api-keys/{id}/delegations/{accountId}

액세스: 부트스트랩 키(설치 복구 키) · 재시도: 예상 리비전으로만 반복(compare-and-swap)

키 id가 주어진 actions(service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read)로 서비스 계정 accountId를 ceiling(넘겨줄 수 있는 리포지토리 바인딩 최대 16개) 안에서 관리하게 합니다. manage는 read를 포함하지 않습니다. expectedRevision은 생성할 때 0이고, 변경하거나 다시 활성화할 때는 레코드의 현재 리비전이어야 하며 그렇지 않으면 409입니다. 키는 활성 상태이고 부트스트랩 키가 발급한 것이어야 하며, 계정은 위임을 가지면서 동시에 위임의 대상이 될 수 없으므로 위임은 연쇄되지 않습니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`accountId`	경로	string (uuid)	예	—

요청 본문 (application/json)

필드	형식	필수	규칙
`expectedRevision`	integer	예	0–2147483646
`actions`	string 배열	예	요소 1–7개; 중복 항목 없음; 각 요소: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read` 중 하나
`ceiling`	object 배열	예	요소 16개 이하
`ceiling[].resource`	object	예	—
`ceiling[].resource.kind`	string	예	`repository` 중 하나
`ceiling[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`ceiling[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답 200

필드	형식	필수	규칙
`keyId`	string (uuid)	예	—
`targetAccountId`	string (uuid)	예	—
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`actions`	string 배열	예	요소 7개 이하; 중복 항목 없음; 각 요소: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read` 중 하나
`ceiling`	object 배열	예	요소 16개 이하
`ceiling[].resource`	object	예	—
`ceiling[].resource.kind`	string	예	`repository` 중 하나
`ceiling[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`ceiling[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X PUT "$ARKVORY_URL/api/v1/api-keys/$ID/delegations/$ACCOUNTID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"actions":["service-account.read"],"ceiling":[]}'

위임 철회

DELETE /api/v1/api-keys/{id}/delegations/{accountId}

액세스: 부트스트랩 키(설치 복구 키) · 재시도: 예상 리비전으로만 반복(compare-and-swap)

키 id의 accountId에 대한 위임을 비활성화하며, JSON 본문에 레코드의 현재 리비전인 expectedRevision이 있어야 합니다. 레코드는 액션이 없고 리비전이 더 높은 비활성 항목으로 남으며 200으로 반환됩니다. 응답을 받지 못했다면 이전 리비전은 409가 되므로 반복하지 말고 listServiceDelegations로 읽습니다. 위임받은 키가 이미 발급해 활성화한 키는 계속 동작하므로 별도로 폐기하거나 계정을 비활성화합니다.

매개 변수

이름	위치	형식	필수	규칙
`id`	경로	string (uuid)	예	—
`accountId`	경로	string (uuid)	예	—

요청 본문 (application/json)

필드	형식	필수	규칙
`expectedRevision`	integer	예	1–2147483646

응답 200

필드	형식	필수	규칙
`keyId`	string (uuid)	예	—
`targetAccountId`	string (uuid)	예	—
`enabled`	boolean	예	—
`revision`	integer	예	1–2147483647
`actions`	string 배열	예	요소 7개 이하; 중복 항목 없음; 각 요소: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read` 중 하나
`ceiling`	object 배열	예	요소 16개 이하
`ceiling[].resource`	object	예	—
`ceiling[].resource.kind`	string	예	`repository` 중 하나
`ceiling[].resource.id`	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`ceiling[].actions`	string 배열	예	요소 1–24개; 중복 항목 없음; 각 요소: `repository.read`, `storage.read`, `storage.manage`, `diagnostics.read`, `artifact.read`, `artifact.list`, `artifact.delete`, `artifact.promote`, `content.read`, `upload.create`, `upload.read`, `upload.write`, `upload.complete`, `upload.cancel`, `job.read`, `package.read`, `package.publish`, `asset.read`, `asset.write`, `asset.restore`, `annotation.read`, `annotation.write`, `reference.write`, `audit.read` 중 하나

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X DELETE "$ARKVORY_URL/api/v1/api-keys/$ID/delegations/$ACCOUNTID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1}'

서비스 계정 및 키 ​

작업 ​

서비스 계정 목록 ​

서비스 계정 생성 ​

서비스 계정 조회 ​

서비스 계정 활성화 또는 비활성화 ​

서비스 계정 정책 조회 ​

서비스 계정 정책 교체 ​

서비스 계정의 키 목록 ​

서비스 계정의 키 발급 ​

서비스 계정 감사 기록 조회 ​

키 조회 ​

키 교체 ​

키 폐기 ​

키 활성화 ​

키의 위임 목록 ​

서비스 계정 관리 위임 ​

위임 철회 ​

서비스 계정 및 키

작업

서비스 계정 목록

서비스 계정 생성

서비스 계정 조회

서비스 계정 활성화 또는 비활성화

서비스 계정 정책 조회

서비스 계정 정책 교체

서비스 계정의 키 목록

서비스 계정의 키 발급

서비스 계정 감사 기록 조회

키 조회

키 교체

키 폐기

키 활성화

키의 위임 목록

서비스 계정 관리 위임

위임 철회