Saltar al contenido

Cuentas e inicio de sesión ​

Inicio de sesión, sesiones, tokens de acceso personal, usuarios, grupos y la auditoría de seguridad.

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 ​

Iniciar sesión ​

POST /api/v1/auth/login

Acceso: Cualquiera, sin clave · Reintento: No repetir automáticamente

Intercambia el name y la password de una cuenta por un token de sesión bearer válido durante 12 horas, con su expiresAt y la cuenta; envíelo como Authorization: Bearer. Un nombre desconocido, una contraseña incorrecta y una cuenta desactivada responden todos con el mismo 401 invalid_credentials. Los intentos se limitan por dirección de cliente y por cuenta (429 rate_limited con Retry-After), y una cuenta conserva como máximo 32 sesiones: una nueva termina la más antigua.

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
namestringsí—
passwordstring (password)sí—

Respuesta 200

CampoTipoObligatorioReglas
tokenstringsí—
expiresAtstring (date-time)sí—
accountobjectsí—
account.idstring (uuid)sí—
account.namestringsí—
account.administratorbooleansí—
account.enabledbooleansí—

Respuestas: 200, 400, 401, 403, 405, 413, 415, 429, 503

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","password":"<password>"}'

Registrar una cuenta ​

POST /api/v1/auth/register

Acceso: Cualquiera, sin clave · Reintento: No repetir automáticamente

Crea una cuenta ordinaria (nunca de administrador) con name (3–64 letras, dígitos o _.-) y password (12–128 caracteres) e inicia sesión con ella, respondiendo 201 con una sesión de 12 horas como login. Solo funciona cuando el servidor permite el autorregistro (véase getAuthOptions); de lo contrario, 403 registration_disabled; un nombre ocupado produce un 409 already_exists. Los intentos se limitan por dirección de cliente (429 con Retry-After), y el autorregistro se detiene en 900 cuentas.

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
namestringsí—
passwordstring (password)sí—

Respuesta 201

CampoTipoObligatorioReglas
tokenstringsí—
expiresAtstring (date-time)sí—
accountobjectsí—
account.idstring (uuid)sí—
account.namestringsí—
account.administratorbooleansí—
account.enabledbooleansí—

Respuestas: 201, 400, 403, 405, 413, 415, 429, 503

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","password":"<password>"}'

Obtener las opciones de inicio de sesión ​

GET HEAD /api/v1/auth/options

Acceso: Cualquiera, sin clave · Reintento: Se puede repetir (lectura)

Indica a una consola, antes del inicio de sesión, qué formularios mostrar: selfRegistration es verdadero cuando registerAccount está abierto en este servidor.

Respuesta 200

CampoTipoObligatorioReglas
selfRegistrationbooleansí—

Respuestas: 200, 400, 403, 503

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/options"

Listar sus tokens de acceso personal ​

GET HEAD /api/v1/auth/tokens

Acceso: Una sesión de cuenta iniciada (no una clave) · Reintento: Se puede repetir (lectura)

Enumera los tokens de acceso personal de la cuenta con sesión iniciada, primero los activos, con nombre, prefijo, ámbito, creación, caducidad, último uso e indicación de si está revocado; los secretos nunca se vuelven a mostrar.

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].idstring (uuid)sí—
items[].namestringsí—
items[].prefixstringsí—
items[].scopestringsíuno de read, read-write
items[].createdAtstring (date-time)sí—
items[].expiresAtstring (date-time)nopuede ser null
items[].lastUsedAtstring (date-time)nopuede ser null
items[].revokedbooleansí—

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

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/tokens" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Crear un token de acceso personal ​

POST /api/v1/auth/tokens

Acceso: Una sesión de cuenta iniciada (no una clave) · Reintento: No repetir automáticamente

Crea un token para scripts y herramientas que actúa como la cuenta con sesión iniciada; el secreto aparece solo en esta respuesta. name tiene 1–64 caracteres, expiresAt es por defecto de 90 días a partir de ahora y debe estar en el futuro y dentro de 365 días, y scope es read-write (por defecto) o read, que nunca puede cambiar nada. Los tokens nunca llevan derechos de administrador, no pueden crear tokens, y una cuenta tiene como máximo 50 activos (507 token_limit).

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
namestringsí—
expiresAtstring (date-time)no—
scopestringnouno de read, read-write

Respuesta 201

CampoTipoObligatorioReglas
idstring (uuid)sí—
namestringsí—
prefixstringsí—
scopestringsíuno de read, read-write
createdAtstring (date-time)sí—
expiresAtstring (date-time)nopuede ser null
lastUsedAtstring (date-time)nopuede ser null
revokedbooleansí—
tokenstringsí—

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

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/auth/tokens" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

Revocar su token de acceso personal ​

DELETE /api/v1/auth/tokens/{id}

Acceso: Una sesión de cuenta iniciada (no una clave) · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Revoca un token de acceso personal de la cuenta con sesión iniciada; las solicitudes con él fallan a partir de ahora. Revocar un token ya revocado también se completa con éxito.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—

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

Ejemplo

bash
curl -X DELETE "$ARKVORY_URL/api/v1/auth/tokens/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Cerrar sesión ​

POST /api/v1/auth/logout

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Termina la sesión de cuenta enviada en Authorization; su token deja de funcionar de inmediato. Con cualquier otra credencial (un token personal o una clave de servicio) responde 204 y no revoca nada.

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

Ejemplo

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

Cambiar su contraseña ​

POST /api/v1/auth/password

Acceso: Una sesión de cuenta iniciada (no una clave) · Reintento: No repetir automáticamente

Establece newPassword (12–128 caracteres) tras comprobar currentPassword; una contraseña actual incorrecta produce un 401 current_password_invalid y cuenta para la espera progresiva de los intentos de inicio de sesión. Si tiene éxito, se revocan todas las sesiones y todos los tokens de acceso personal de la cuenta, incluida la sesión actual, así que vuelva a iniciar sesión.

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
currentPasswordstring (password)sí—
newPasswordstring (password)sí—

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

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/auth/password" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"<currentPassword>","newPassword":"<newPassword>"}'

Obtener la identidad actual ​

GET HEAD /api/v1/auth/me

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Devuelve a quién pertenece la credencial: su id, si es administrador, el tipo de credencial (session, personal-token, service-key o file-key), el ámbito de un token personal y los repositorios a los que tiene acceso de read o write. Úselo para mostrar al usuario con sesión iniciada y para elegir un repositorio; para los permisos exactos de una clave de servicio administrada use getOwnPermissions.

Respuesta 200

CampoTipoObligatorioReglas
idstringsí—
administratorbooleansí—
credentialstringnouno de session, personal-token, service-key, file-key
tokenScopestringnouno de read, read-write
grantsarray de objectsí—
grants[].repositorystringsí—
grants[].permissionsarray de stringsícada elemento: uno de read, write

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

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/me" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Listar cuentas ​

GET HEAD /api/v1/users

Acceso: Administrador · Reintento: Se puede repetir (lectura)

Enumera todas las cuentas de usuario ordenadas por nombre, con ID, nombre, indicador de administrador y si están activadas. El servidor admite como máximo 1000 cuentas.

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectno—
items[].idstring (uuid)sí—
items[].namestringsí—
items[].administratorbooleansí—
items[].enabledbooleansí—

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

Ejemplo

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

Crear una cuenta ​

POST /api/v1/users

Acceso: Administrador · Reintento: No repetir automáticamente

Crea una cuenta con name (3–64 letras, dígitos o _.-), password (12–128 caracteres) y administrator (falso por defecto), y responde 201 con ella. Un nombre ocupado produce un 409 already_exists; el servidor admite como máximo 1000 cuentas (507 account_limit).

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
namestringsí—
passwordstring (password)sí—
administratorbooleanno—

Respuesta 201

CampoTipoObligatorioReglas
idstring (uuid)sí—
namestringsí—
administratorbooleansí—
enabledbooleansí—

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

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/users" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","password":"<password>"}'

Activar, desactivar o restablecer una cuenta ​

PATCH /api/v1/users/{id}

Acceso: Administrador · Reintento: No repetir automáticamente

Cambia enabled o establece una nueva password de una cuenta, o ambos; el indicador de administrador no se puede cambiar aquí. Desactivar termina todas las sesiones de la cuenta, y sus tokens personales dejan de funcionar mientras siga desactivada; un restablecimiento de contraseña termina todas las sesiones y revoca todos los tokens personales.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
enabledbooleanno—
passwordstring (password)no—

Respuesta 200

CampoTipoObligatorioReglas
idstring (uuid)sí—
namestringsí—
administratorbooleansí—
enabledbooleansí—

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

Ejemplo

bash
curl -X PATCH "$ARKVORY_URL/api/v1/users/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Listar los tokens de acceso personal de una cuenta ​

GET HEAD /api/v1/users/{id}/tokens

Acceso: Administrador · Reintento: Se puede repetir (lectura)

Enumera los tokens de acceso personal de cualquier cuenta, primero los activos, con nombre, prefijo, ámbito, creación, caducidad, último uso y revocación; nunca los secretos. Úselo para revisar la automatización antes de desactivar o restablecer la cuenta.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].idstring (uuid)sí—
items[].namestringsí—
items[].prefixstringsí—
items[].scopestringsíuno de read, read-write
items[].createdAtstring (date-time)sí—
items[].expiresAtstring (date-time)nopuede ser null
items[].lastUsedAtstring (date-time)nopuede ser null
items[].revokedbooleansí—

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

Ejemplo

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

Revocar un token de acceso personal de una cuenta ​

DELETE /api/v1/users/{id}/tokens/{tokenId}

Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Revoca un token de acceso personal de la cuenta id; las solicitudes con él fallan a partir de ahora, y el evento se registra en la auditoría de seguridad. Revocar un token ya revocado también se completa con éxito.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—
tokenIdrutastring (uuid)sí—

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

Ejemplo

bash
curl -X DELETE "$ARKVORY_URL/api/v1/users/$ID/tokens/$TOKENID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Listar grupos de acceso ​

GET HEAD /api/v1/access-groups

Acceso: Administrador · Reintento: Se puede repetir (lectura)

Enumera todos los grupos de acceso con los ID de las cuentas miembros y las concesiones de repositorio (read o write). El servidor admite como máximo 100 grupos, 10 000 pertenencias y 10 000 concesiones.

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectno—
items[].idstring (uuid)sí—
items[].namestringsí—
items[].membersarray de string (uuid)sí—
items[].grantsarray de objectsí—
items[].grants[].repositorystringsí—
items[].grants[].accessstringsíuno de read, write

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

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/access-groups" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Crear un grupo de acceso ​

POST /api/v1/access-groups

Acceso: Administrador · Reintento: No repetir automáticamente

Crea un grupo vacío con name (2–64 letras, dígitos o _.-) y responde 201 con él; un nombre ocupado produce un 409 already_exists. Añada miembros con addGroupMember y repositorios con setGroupGrant.

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
namestringsí—

Respuesta 201

CampoTipoObligatorioReglas
idstring (uuid)sí—
namestringsí—
membersarray de string (uuid)sí—
grantsarray de objectsí—
grants[].repositorystringsí—
grants[].accessstringsíuno de read, write

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

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/access-groups" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'

Añadir una cuenta a un grupo ​

PUT /api/v1/access-groups/{id}/members/{userId}

Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Hace que la cuenta userId sea miembro del grupo; obtiene el acceso del grupo a los repositorios con su siguiente solicitud. Añadir a un miembro existente no cambia nada; como máximo 10 000 pertenencias en total (507 membership_limit).

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—
userIdrutastring (uuid)sí—

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

Ejemplo

bash
curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Quitar una cuenta de un grupo ​

DELETE /api/v1/access-groups/{id}/members/{userId}

Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Quita la cuenta userId del grupo; el acceso que tenía a través del grupo termina con su siguiente solicitud. Quitar una cuenta que no es miembro también se completa con éxito.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—
userIdrutastring (uuid)sí—

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

Ejemplo

bash
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Conceder a un grupo acceso a un repositorio ​

PUT /api/v1/access-groups/{id}/grants/{repository}

Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Da a los miembros del grupo acceso read o write (access) a repository, reemplazando una concesión anterior del grupo allí; se aplica desde su siguiente solicitud. Un repositorio no necesita una creación aparte: la concesión se lo hace visible. Como máximo 10 000 concesiones en total (507 grant_limit).

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—
repositoryrutastringsí—

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
accessstringsíuno de read, write

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

Ejemplo

bash
curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access":"read"}'

Quitar el acceso de un grupo a un repositorio ​

DELETE /api/v1/access-groups/{id}/grants/{repository}

Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Quita la concesión del grupo para repository; sus miembros conservan solo el acceso que tienen a través de otros grupos. Quitar una concesión que no existe también se completa con éxito.

Parámetros

NombreUbicaciónTipoObligatorioReglas
idrutastring (uuid)sí—
repositoryrutastringsí—

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

Ejemplo

bash
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Leer la auditoría de seguridad ​

GET HEAD /api/v1/security/audit

Acceso: Administrador · Reintento: Se puede repetir (lectura)

Devuelve el diario de solo adición (append-only) de inicios de sesión, registros y cambios de cuentas, grupos, concesiones, contraseñas y tokens de acceso personal, del más reciente al más antiguo, cada uno con actor, tipo de credencial, destino, resultado y dirección del cliente; los intentos limitados por frecuencia no se registran en él. Las páginas contienen limit entradas (1–100, 50 por defecto); continúe pasando next como after.

Parámetros

NombreUbicaciónTipoObligatorioReglas
afterconsultastringnoun número entero en dígitos decimales, enviado como cadena
limitconsultaintegerno1–100

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].idstringsíun número entero en dígitos decimales, enviado como cadena
items[].occurredAtstring (date-time)sí—
items[].actorstringsípuede ser null
items[].credentialstringsíuno de session, personal-token, service-key, file-key; puede ser null
items[].clientIpstringsípuede ser null
items[].actionstringsí—
items[].targetstringsípuede ser null
items[].outcomestringsíuno de success, failure, denied
items[].codestringsípuede ser null
items[].detailsobjectsí—
nextstringsípuede ser null

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

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/security/audit" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener sus permisos efectivos ​

GET HEAD /api/v1/auth/permissions

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Devuelve el profile del solicitante (managed para una clave de servicio administrada, legacy en otro caso), el ID de su clave, sus vinculaciones efectivas (cada repositorio con las acciones exactas permitidas en él) y si es el administrador de servicio inicial (bootstrap). Úselo para adaptar un cliente; el servidor sigue comprobando cada solicitud, así que un cambio de permisos se aplica de inmediato.

Respuesta 200

CampoTipoObligatorioReglas
idstringsí—
profilestringsíuno de legacy, managed
bindingsarray de objectsíhasta 10000 elementos
bindings[].resourceobjectsí—
bindings[].resource.kindstringsíuno de repository
bindings[].resource.idstringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$
bindings[].actionsarray de stringsí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
serviceAdministrationbooleansí—
credentialIdstring (uuid)nopuede ser null

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

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/auth/permissions" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Arkvory · ProAnimaStudio