Cuentas de servicio y claves

Cuentas de servicio para CI y automatización, sus claves, políticas, delegaciones y auditoría.

Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).

Operaciones

Listar cuentas de servicio

GET HEAD /api/v1/service-accounts

Acceso: Permiso de administración de servicios service-account.read · Reintento: Se puede repetir (lectura)

Enumera las cuentas de servicio que el solicitante puede ver, ordenadas por ID, 50 por página, cada una con nombre, indicador de activación, revision, bindings de la política y hora de creación; continúe pasando next como after. La clave de recuperación (bootstrap) las ve todas; un delegado, solo los destinos en los que su delegación incluye service-account.read; sin ello la lista queda vacía en lugar de rechazarse.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
after	consulta	string (uuid)	no	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 50 elementos
items[].id	string (uuid)	sí	—
items[].name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
items[].enabled	boolean	sí	—
items[].revision	integer	sí	1–2147483647
items[].bindings	array de object	sí	hasta 64 elementos
items[].bindings[].resource	object	sí	—
items[].bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—
next	string (uuid)	sí	puede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Crear una cuenta de servicio

POST /api/v1/service-accounts

Acceso: Clave de arranque (clave de recuperación de la instalación) · Reintento: No repetir automáticamente

Crea una identidad de máquina para CI o una aplicación con name (3–64 letras, dígitos o _.-) y los bindings de su política: para cada repositorio, las acciones exactas que sus claves pueden usar (como upload.create o content.read). Responde 201 con la cuenta; después emita una clave con issueServiceKey. Un nombre ocupado produce un 409 already_exists.

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

Respuesta 201

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—

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

Ejemplo

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

Obtener una cuenta de servicio

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

Acceso: Permiso de administración de servicios service-account.read · Reintento: Se puede repetir (lectura)

Devuelve el nombre de la cuenta, el indicador de activación, la revision, las vinculaciones de la política y la hora de creación. Para un delegado, una cuenta que no se le asignó responde 404, y la falta de una acción en una cuenta asignada, 403.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Activar o desactivar una cuenta de servicio

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

Acceso: Permiso de administración de servicios service-account.manage · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Establece enabled; expectedRevision debe ser la revisión actual; de lo contrario, 409 revision_mismatch. Aquí solo cambia este indicador (el nombre no puede cambiar). Desactivar bloquea todas las claves de la cuenta desde la siguiente solicitud; activar reactiva las claves que no han caducado ni se han revocado. Un delegado solo puede hacerlo cuando toda la política actual está dentro de su tope.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
expectedRevision	integer	sí	1–2147483646
enabled	boolean	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—

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

Ejemplo

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}'

Obtener la política de una cuenta de servicio

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

Acceso: Permiso de administración de servicios policy.read · Reintento: Se puede repetir (lectura)

Devuelve la cuenta con los bindings de su política y la revision, como getServiceAccount, para un solicitante que tiene policy.read. Los permisos efectivos de una clave son la intersección de esta política y las vinculaciones propias de la clave, por repositorio y acción.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Reemplazar la política de una cuenta de servicio

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

Acceso: Permiso de administración de servicios policy.manage · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Reemplaza los bindings de la cuenta (hasta 64, cada uno un repositorio con sus acciones exactas); expectedRevision debe ser la revisión actual; de lo contrario, 409 revision_mismatch. Todas las claves siguen el cambio desde su siguiente solicitud: restringir surte efecto de inmediato, y ampliar nunca supera las vinculaciones propias de una clave. Un delegado necesita que tanto la política actual como la nueva estén dentro de su tope.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
expectedRevision	integer	sí	1–2147483646
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—

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

Ejemplo

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":[]}'

Listar las claves de una cuenta de servicio

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

Acceso: Permiso de administración de servicios credential.read · Reintento: Se puede repetir (lectura)

Enumera los metadatos de las claves de la cuenta ordenadas por ID, 50 por página: nombre, state (pending, active, revoked), vinculaciones, creación, caducidad, plazo de activación y la clave anterior de la que procede por rotación; nunca secretos ni hashes. Continúe pasando next como after. La caducidad no cambia state, así que compare expiresAt con la hora actual.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
after	consulta	string (uuid)	no	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 50 elementos
items[].id	string (uuid)	sí	—
items[].accountId	string (uuid)	sí	—
items[].name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
items[].state	string	sí	uno de pending, active, revoked
items[].bindings	array de object	sí	hasta 64 elementos
items[].bindings[].resource	object	sí	—
items[].bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—
items[].expiresAt	string (date-time)	sí	—
items[].activationExpiresAt	string (date-time)	sí	—
items[].rotatedFrom	string (uuid)	sí	puede ser null
next	string (uuid)	sí	puede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Emitir una clave para una cuenta de servicio

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

Acceso: Permiso de administración de servicios credential.manage · Reintento: Se puede repetir con el mismo Idempotency-Key

Emite una clave pendiente con name, bindings (efectivos solo donde la política de la cuenta también los permite) y un expiresAt opcional (UTC; 90 días por defecto, como máximo 365 y, para un delegado, nunca más allá de su propia clave). La primera respuesta es 201 con key y el secret, que se muestra solo esta vez; una repetición con la misma Idempotency-Key y el mismo cuerpo da 200 solo con los metadatos, y un cuerpo distinto, un 409. El titular debe llamar a activateServiceKey con el secreto en un plazo de 15 minutos; si se perdió el secreto, revoque la clave y emita una nueva con una clave Idempotency-Key nueva.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
Idempotency-Key	encabezado	string	sí	hasta 128 caracteres

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	no	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
key	object	sí	—
key.id	string (uuid)	sí	—
key.accountId	string (uuid)	sí	—
key.name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
key.state	string	sí	uno de pending, active, revoked
key.bindings	array de object	sí	hasta 64 elementos
key.bindings[].resource	object	sí	—
key.bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—
key.expiresAt	string (date-time)	sí	—
key.activationExpiresAt	string (date-time)	sí	—
key.rotatedFrom	string (uuid)	sí	puede ser null
secret	string	no	—

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

Ejemplo

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":[]}'

Leer la auditoría de una cuenta de servicio

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

Acceso: Permiso de administración de servicios service-audit.read · Reintento: Se puede repetir (lectura)

Devuelve, del más antiguo al más reciente, hasta 100 eventos de la cuenta posteriores a la secuencia after (0 por defecto): cambios de la cuenta, de la política y de las claves, como emisión, rotación, activación y revocación, cada uno con actor, acción, clave y hora. Para seguir leyendo, pase el último sequence como after; no hay campo next. Solo se conservan los 100 000 eventos más recientes del servidor.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
after	consulta	string	no	un número entero en dígitos decimales, enviado como cadena

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 100 elementos
items[].sequence	string	sí	—
items[].actor	string	sí	—
items[].action	string	sí	—
items[].accountId	string (uuid)	sí	—
items[].keyId	string (uuid)	sí	puede ser null
items[].occurredAt	string (date-time)	sí	—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Obtener una clave

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

Acceso: Permiso de administración de servicios credential.read · Reintento: Se puede repetir (lectura)

Devuelve los metadatos de una clave administrada: su cuenta, nombre, estado, vinculaciones, creación, caducidad, plazo de activación y la clave anterior de la que procede por rotación; nunca el secreto ni su hash.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
accountId	string (uuid)	sí	—
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
state	string	sí	uno de pending, active, revoked
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—
expiresAt	string (date-time)	sí	—
activationExpiresAt	string (date-time)	sí	—
rotatedFrom	string (uuid)	sí	puede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Rotar una clave

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

Acceso: Permiso de administración de servicios credential.manage · Reintento: Se puede repetir con el mismo Idempotency-Key

Emite una clave sucesora pendiente de la clave id para la misma cuenta con los mismos bindings o con otros más restringidos, y responde como issueServiceKey: 201 con el secret de un solo uso, 200 solo con metadatos en una repetición con la misma Idempotency-Key. Una vez activada la sucesora, la clave antigua sigue siendo válida como máximo 24 horas más; revóquela explícitamente cuando la nueva funcione, pero solo después de que hayan terminado los trabajos que inició. Las delegaciones que tiene una clave de operador no se copian a su sucesora.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
Idempotency-Key	encabezado	string	sí	hasta 128 caracteres

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
bindings	array de object	sí	hasta 64 elementos
bindings[].resource	object	sí	—
bindings[].resource.kind	string	sí	uno de repository
bindings[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	no	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
key	object	sí	—
key.id	string (uuid)	sí	—
key.accountId	string (uuid)	sí	—
key.name	string	sí	coincide con ^[a-zA-Z0-9_.-]{3,64}$
key.state	string	sí	uno de pending, active, revoked
key.bindings	array de object	sí	hasta 64 elementos
key.bindings[].resource	object	sí	—
key.bindings[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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)	sí	—
key.expiresAt	string (date-time)	sí	—
key.activationExpiresAt	string (date-time)	sí	—
key.rotatedFrom	string (uuid)	sí	puede ser null
secret	string	no	—

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

Ejemplo

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":[]}'

Revocar una clave

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

Acceso: Permiso de administración de servicios credential.manage · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Revoca la clave de forma definitiva: su siguiente solicitud falla, mientras que una descarga que ya está en curso no se interrumpe. Repetirlo termina con éxito con 204. Las claves que emitió una clave de operador revocada y que ya se activaron siguen siendo válidas; revóquelas por separado.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

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

Ejemplo

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

Activar una clave

POST /api/v1/auth/activate-key

Acceso: La clave emitida, antes o después de su activación · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Demuestra que el titular recibió una clave recién emitida: llámelo con esa clave como Authorization: Bearer en los 15 minutos siguientes a la emisión, y la clave pasa a estar activa (204). Repetirlo es seguro y no prolonga la caducidad. Activar una clave rotada reduce a un máximo de 24 horas la vida restante de la clave a la que sustituye.

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

Ejemplo

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

Listar las delegaciones de una clave

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

Acceso: Clave de arranque o la propia clave · Reintento: Se puede repetir (lectura)

Devuelve las delegaciones que tiene la clave de operador id, hasta 64 incluidas las desactivadas: para cada cuenta de destino, su revision, si está enabled, las actions de administración (como credential.manage) y el ceiling de vinculaciones de repositorio que puede conceder. Un delegado lee aquí las suyas (el ID de su clave es credentialId en getOwnPermissions); la lista de otra clave produce un 403.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 64 elementos
items[].keyId	string (uuid)	sí	—
items[].targetAccountId	string (uuid)	sí	—
items[].enabled	boolean	sí	—
items[].revision	integer	sí	1–2147483647
items[].actions	array de string	sí	hasta 7 elementos; sin elementos repetidos; cada elemento: uno de service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read
items[].ceiling	array de object	sí	hasta 16 elementos
items[].ceiling[].resource	object	sí	—
items[].ceiling[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

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

Delegar la administración de una cuenta de servicio

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

Acceso: Clave de arranque (clave de recuperación de la instalación) · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Permite que la clave id administre la cuenta de servicio accountId con las actions indicadas (service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read) dentro de ceiling, hasta 16 vinculaciones de repositorio que puede conceder; manage no implica read. expectedRevision es 0 para crear y la revisión actual del registro para modificarlo o reactivarlo; de lo contrario, 409. La clave debe estar activa y haber sido emitida por la clave de recuperación (bootstrap), y una cuenta no puede tener delegaciones y a la vez ser el destino de una, de modo que la delegación nunca se encadena.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
accountId	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
expectedRevision	integer	sí	0–2147483646
actions	array de string	sí	1–7 elementos; sin elementos repetidos; cada elemento: uno de service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read
ceiling	array de object	sí	hasta 16 elementos
ceiling[].resource	object	sí	—
ceiling[].resource.kind	string	sí	uno de repository
ceiling[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
ceiling[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
keyId	string (uuid)	sí	—
targetAccountId	string (uuid)	sí	—
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
actions	array de string	sí	hasta 7 elementos; sin elementos repetidos; cada elemento: uno de service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read
ceiling	array de object	sí	hasta 16 elementos
ceiling[].resource	object	sí	—
ceiling[].resource.kind	string	sí	uno de repository
ceiling[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
ceiling[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

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

Ejemplo

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":[]}'

Retirar una delegación

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

Acceso: Clave de arranque (clave de recuperación de la instalación) · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Desactiva la delegación de la clave id sobre accountId; el cuerpo JSON lleva expectedRevision, la revisión actual del registro. El registro permanece como una entrada desactivada, sin acciones y con una revisión superior, que se devuelve con 200; tras perder la respuesta, léalo con listServiceDelegations en lugar de repetir, ya que la revisión antigua produce un 409. Las claves que el delegado ya emitió y activó siguen funcionando: revóquelas o desactive la cuenta por separado.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
accountId	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
expectedRevision	integer	sí	1–2147483646

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
keyId	string (uuid)	sí	—
targetAccountId	string (uuid)	sí	—
enabled	boolean	sí	—
revision	integer	sí	1–2147483647
actions	array de string	sí	hasta 7 elementos; sin elementos repetidos; cada elemento: uno de service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read
ceiling	array de object	sí	hasta 16 elementos
ceiling[].resource	object	sí	—
ceiling[].resource.kind	string	sí	uno de repository
ceiling[].resource.id	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
ceiling[].actions	array de string	sí	1–24 elementos; sin elementos repetidos; cada elemento: uno de 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

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

Ejemplo

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}'