Contas e login
Login, sessões, tokens de acesso pessoal, usuários, grupos e a auditoria de segurança.
Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).
Operações
Fazer login
POST /api/v1/auth/login
Acesso: Qualquer pessoa, sem chave · Repetição: Não repetir automaticamente
Troca o name e a password de uma conta por um token de sessão bearer válido por 12 horas, com seu expiresAt e a conta; envie-o como Authorization: Bearer. Um nome desconhecido, uma senha incorreta e uma conta desativada respondem todos com o mesmo 401 invalid_credentials. As tentativas são limitadas por endereço de cliente e por conta (429 rate_limited com Retry-After), e uma conta mantém no máximo 32 sessões: uma nova encerra a mais antiga.
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | — |
password | string (password) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
token | string | sim | — |
expiresAt | string (date-time) | sim | — |
account | object | sim | — |
account.id | string (uuid) | sim | — |
account.name | string | sim | — |
account.administrator | boolean | sim | — |
account.enabled | boolean | sim | — |
Respostas: 200, 400, 401, 403, 405, 413, 415, 429, 503
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Registrar uma conta
POST /api/v1/auth/register
Acesso: Qualquer pessoa, sem chave · Repetição: Não repetir automaticamente
Cria uma conta comum (nunca uma de administrador) com name (3–64 letras, dígitos ou _.-) e password (12–128 caracteres) e já inicia a sessão dela, respondendo 201 com uma sessão de 12 horas, como login. Funciona somente quando o servidor permite o autocadastro (veja getAuthOptions); caso contrário, 403 registration_disabled; um nome já em uso gera 409 already_exists. As tentativas são limitadas por endereço de cliente (429 com Retry-After), e o autocadastro é interrompido em 900 contas.
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | — |
password | string (password) | sim | — |
Resposta 201
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
token | string | sim | — |
expiresAt | string (date-time) | sim | — |
account | object | sim | — |
account.id | string (uuid) | sim | — |
account.name | string | sim | — |
account.administrator | boolean | sim | — |
account.enabled | boolean | sim | — |
Respostas: 201, 400, 403, 405, 413, 415, 429, 503
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Obter as opções de login
GET HEAD /api/v1/auth/options
Acesso: Qualquer pessoa, sem chave · Repetição: Pode ser repetida com segurança (leitura)
Informa a um console, antes do login, quais formulários mostrar: selfRegistration é true quando registerAccount está disponível neste servidor.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
selfRegistration | boolean | sim | — |
Respostas: 200, 400, 403, 503
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/auth/options"Listar seus tokens de acesso pessoal
GET HEAD /api/v1/auth/tokens
Acesso: Uma sessão de conta iniciada (não uma chave) · Repetição: Pode ser repetida com segurança (leitura)
Lista os tokens de acesso pessoal da conta autenticada, os ativos primeiro, com nome, prefixo, escopo, criação, expiração, último uso e se foi revogado; os segredos nunca são mostrados novamente.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].id | string (uuid) | sim | — |
items[].name | string | sim | — |
items[].prefix | string | sim | — |
items[].scope | string | sim | um destes: read, read-write |
items[].createdAt | string (date-time) | sim | — |
items[].expiresAt | string (date-time) | não | pode ser null |
items[].lastUsedAt | string (date-time) | não | pode ser null |
items[].revoked | boolean | sim | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/auth/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Criar um token de acesso pessoal
POST /api/v1/auth/tokens
Acesso: Uma sessão de conta iniciada (não uma chave) · Repetição: Não repetir automaticamente
Cria um token para scripts e ferramentas que age como a conta autenticada; o segredo aparece somente nesta resposta. name tem de 1 a 64 caracteres, expiresAt é de 90 dias por padrão e deve estar no futuro e dentro de 365 dias, e scope é read-write (padrão) ou read, que nunca pode alterar nada. Os tokens nunca carregam direitos de administrador, não podem criar tokens, e uma conta tem no máximo 50 tokens ativos (507 token_limit).
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | — |
expiresAt | string (date-time) | não | — |
scope | string | não | um destes: read, read-write |
Resposta 201
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
name | string | sim | — |
prefix | string | sim | — |
scope | string | sim | um destes: read, read-write |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | não | pode ser null |
lastUsedAt | string (date-time) | não | pode ser null |
revoked | boolean | sim | — |
token | string | sim | — |
Respostas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/auth/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Revogar seu token de acesso pessoal
DELETE /api/v1/auth/tokens/{id}
Acesso: Uma sessão de conta iniciada (não uma chave) · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Revoga um token de acesso pessoal da conta autenticada; as solicitações feitas com ele falham a partir de agora. Revogar um token já revogado também tem sucesso.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/auth/tokens/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Sair
POST /api/v1/auth/logout
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Encerra a sessão de conta enviada em Authorization; seu token deixa de funcionar imediatamente. Com qualquer outra credencial (um token pessoal ou uma chave de serviço), responde 204 e não revoga nada.
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/auth/logout" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Alterar sua senha
POST /api/v1/auth/password
Acesso: Uma sessão de conta iniciada (não uma chave) · Repetição: Não repetir automaticamente
Define newPassword (12–128 caracteres) após verificar currentPassword; uma senha atual incorreta gera 401 current_password_invalid e conta para o backoff de login. Em caso de sucesso, todas as sessões e todos os tokens de acesso pessoal da conta são revogados, inclusive a sessão atual; portanto, faça login novamente.
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
currentPassword | string (password) | sim | — |
newPassword | string (password) | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/auth/password" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currentPassword":"<currentPassword>","newPassword":"<newPassword>"}'Obter a identidade atual
GET HEAD /api/v1/auth/me
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Retorna a quem a credencial pertence: seu id, se é administrador, o tipo de credencial (session, personal-token, service-key ou file-key), o escopo de um token pessoal e os repositórios aos quais ela tem acesso read ou write. Use-o para mostrar o usuário autenticado e escolher um repositório; para as permissões exatas de uma chave de serviço gerenciada, use getOwnPermissions.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string | sim | — |
administrator | boolean | sim | — |
credential | string | não | um destes: session, personal-token, service-key, file-key |
tokenScope | string | não | um destes: read, read-write |
grants | array de object | sim | — |
grants[].repository | string | sim | — |
grants[].permissions | array de string | sim | cada item: um destes: read, write |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/auth/me" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar contas
GET HEAD /api/v1/users
Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)
Lista todas as contas de usuário ordenadas por nome, com ID, nome, indicador de administrador e se estão ativadas. O servidor mantém no máximo 1000 contas.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | não | — |
items[].id | string (uuid) | sim | — |
items[].name | string | sim | — |
items[].administrator | boolean | sim | — |
items[].enabled | boolean | sim | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/users" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Criar uma conta
POST /api/v1/users
Acesso: Administrador · Repetição: Não repetir automaticamente
Cria uma conta com name (3–64 letras, dígitos ou _.-), password (12–128 caracteres) e administrator (padrão false) e responde 201 com ela. Um nome já em uso gera 409 already_exists; o servidor mantém no máximo 1000 contas (507 account_limit).
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | — |
password | string (password) | sim | — |
administrator | boolean | não | — |
Resposta 201
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
name | string | sim | — |
administrator | boolean | sim | — |
enabled | boolean | sim | — |
Respostas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/users" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","password":"<password>"}'Ativar, desativar ou redefinir uma conta
PATCH /api/v1/users/{id}
Acesso: Administrador · Repetição: Não repetir automaticamente
Altera enabled e/ou define uma nova password de uma conta; o indicador de administrador não pode ser alterado aqui. Desativar encerra todas as sessões da conta, e seus tokens de acesso pessoal deixam de funcionar enquanto ela permanecer desativada; uma redefinição de senha encerra todas as sessões e revoga todos os tokens pessoais.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
enabled | boolean | não | — |
password | string (password) | não | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
name | string | sim | — |
administrator | boolean | sim | — |
enabled | boolean | sim | — |
Respostas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X PATCH "$ARKVORY_URL/api/v1/users/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Listar os tokens de acesso pessoal de uma conta
GET HEAD /api/v1/users/{id}/tokens
Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)
Lista os tokens de acesso pessoal de qualquer conta, os ativos primeiro, com nome, prefixo, escopo, criação, expiração, último uso e revogação; nunca os segredos. Use-o para revisar a automação antes de desativar ou redefinir a conta.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].id | string (uuid) | sim | — |
items[].name | string | sim | — |
items[].prefix | string | sim | — |
items[].scope | string | sim | um destes: read, read-write |
items[].createdAt | string (date-time) | sim | — |
items[].expiresAt | string (date-time) | não | pode ser null |
items[].lastUsedAt | string (date-time) | não | pode ser null |
items[].revoked | boolean | sim | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/users/$ID/tokens" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Revogar um token de acesso pessoal de uma conta
DELETE /api/v1/users/{id}/tokens/{tokenId}
Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Revoga um token de acesso pessoal da conta id; as solicitações feitas com ele falham a partir de agora, e o evento é registrado na auditoria de segurança. Revogar um token já revogado também tem sucesso.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
tokenId | caminho | string (uuid) | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/users/$ID/tokens/$TOKENID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar grupos de acesso
GET HEAD /api/v1/access-groups
Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)
Lista todos os grupos de acesso com os IDs das contas membros e as concessões de repositório (read ou write). O servidor mantém no máximo 100 grupos, 10 000 associações e 10 000 concessões.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | não | — |
items[].id | string (uuid) | sim | — |
items[].name | string | sim | — |
items[].members | array de string (uuid) | sim | — |
items[].grants | array de object | sim | — |
items[].grants[].repository | string | sim | — |
items[].grants[].access | string | sim | um destes: read, write |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/access-groups" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Criar um grupo de acesso
POST /api/v1/access-groups
Acesso: Administrador · Repetição: Não repetir automaticamente
Cria um grupo vazio com name (2–64 letras, dígitos ou _.-) e responde 201 com ele; um nome já em uso gera 409 already_exists. Adicione membros com addGroupMember e repositórios com setGroupGrant.
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | — |
Resposta 201
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
name | string | sim | — |
members | array de string (uuid) | sim | — |
grants | array de object | sim | — |
grants[].repository | string | sim | — |
grants[].access | string | sim | um destes: read, write |
Respostas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/access-groups" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Adicionar uma conta a um grupo
PUT /api/v1/access-groups/{id}/members/{userId}
Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Torna a conta userId membro do grupo; ela passa a ter o acesso do grupo aos repositórios a partir da próxima solicitação. Adicionar um membro existente não altera nada; no máximo 10 000 associações no total (507 membership_limit).
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
userId | caminho | string (uuid) | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X PUT "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Remover uma conta de um grupo
DELETE /api/v1/access-groups/{id}/members/{userId}
Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Remove a conta userId do grupo; o acesso que ela tinha por meio do grupo termina na próxima solicitação. Remover uma conta que não é membro também tem sucesso.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
userId | caminho | string (uuid) | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/members/$USERID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Conceder a um grupo acesso a um repositório
PUT /api/v1/access-groups/{id}/grants/{repository}
Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Dá aos membros do grupo o acesso access read ou write a repository, substituindo uma concessão anterior do grupo nesse repositório; vale a partir da próxima solicitação deles. Um repositório não precisa de criação separada: a concessão o torna visível para eles. No máximo 10 000 concessões no total (507 grant_limit).
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
repository | caminho | string | sim | — |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
access | string | sim | um destes: read, write |
Respostas: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
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"}'Remover o acesso de um grupo a um repositório
DELETE /api/v1/access-groups/{id}/grants/{repository}
Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Remove a concessão do grupo para repository; seus membros mantêm apenas o acesso que têm por meio de outros grupos. Remover uma concessão que não existe também tem sucesso.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
repository | caminho | string | sim | — |
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/access-groups/$ID/grants/$REPOSITORY" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Ler a auditoria de segurança
GET HEAD /api/v1/security/audit
Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)
Retorna o diário somente de anexação (append-only) de logins, registros e alterações de contas, grupos, concessões, senhas e tokens de acesso pessoal, do mais recente para o mais antigo, cada um com ator, tipo de credencial, alvo, resultado e endereço do cliente; tentativas limitadas por throttling não são registradas. As páginas contêm limit entradas (1–100, padrão 50); continue com after definido como next.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
after | consulta | string | não | um número inteiro em dígitos decimais, enviado como string |
limit | consulta | integer | não | 1–100 |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].id | string | sim | um número inteiro em dígitos decimais, enviado como string |
items[].occurredAt | string (date-time) | sim | — |
items[].actor | string | sim | pode ser null |
items[].credential | string | sim | um destes: session, personal-token, service-key, file-key; pode ser null |
items[].clientIp | string | sim | pode ser null |
items[].action | string | sim | — |
items[].target | string | sim | pode ser null |
items[].outcome | string | sim | um destes: success, failure, denied |
items[].code | string | sim | pode ser null |
items[].details | object | sim | — |
next | string | sim | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/security/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obter suas permissões efetivas
GET HEAD /api/v1/auth/permissions
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Retorna o profile do chamador (managed para uma chave de serviço gerenciada, legacy nos demais casos), o ID da sua chave, seus vínculos (bindings) efetivos (cada repositório com as ações exatas permitidas nele) e se ele é o administrador de serviço de bootstrap. Use-o para adaptar um cliente; o servidor continua verificando cada solicitação, portanto uma mudança de permissões vale imediatamente.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string | sim | — |
profile | string | sim | um destes: legacy, managed |
bindings | array de object | sim | até 10000 itens |
bindings[].resource | object | sim | — |
bindings[].resource.kind | string | sim | um destes: repository |
bindings[].resource.id | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
bindings[].actions | array de string | sim | 1–24 itens; sem itens repetidos; cada item: um destes: 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 |
serviceAdministration | boolean | sim | — |
credentialId | string (uuid) | não | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/auth/permissions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"