Contas de serviço e chaves

Contas de serviço para CI e automação, com as chaves, políticas, delegações e auditoria delas.

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

Listar contas de serviço

GET HEAD /api/v1/service-accounts

Acesso: Permissão de administração de serviços service-account.read · Repetição: Pode ser repetida com segurança (leitura)

Lista as contas de serviço que o chamador pode ver, ordenadas por ID, 50 por página, cada uma com nome, indicador de ativação, revision, bindings da política e data de criação; continue com after definido como next. A chave de bootstrap vê todas; um delegado vê apenas os alvos cuja delegação inclui service-account.read; sem isso, a lista vem vazia em vez de ser recusada.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`after`	consulta	string (uuid)	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	sim	até 50 itens
`items[].id`	string (uuid)	sim	—
`items[].name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`items[].enabled`	boolean	sim	—
`items[].revision`	integer	sim	1–2147483647
`items[].bindings`	array de object	sim	até 64 itens
`items[].bindings[].resource`	object	sim	—
`items[].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`
`items[].createdAt`	string (date-time)	sim	—
`next`	string (uuid)	sim	pode ser null

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

Exemplo

bash

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

Criar uma conta de serviço

POST /api/v1/service-accounts

Acesso: Chave de bootstrap (chave de recuperação da instalação) · Repetição: Não repetir automaticamente

Cria uma identidade de máquina para CI ou para um aplicativo com name (3–64 letras, dígitos ou _.-) e os bindings da sua política: para cada repositório, as ações exatas que suas chaves podem usar (como upload.create ou content.read). Responde 201 com a conta; depois emita uma chave com issueServiceKey. Um nome já em uso gera 409 already_exists.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	array de object	sim	até 64 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`

Resposta 201

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—

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

Exemplo

bash

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

Obter uma conta de serviço

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

Acesso: Permissão de administração de serviços service-account.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna o nome, o indicador de ativação, a revision, os vínculos da política e a data de criação da conta. Para um delegado, uma conta que não lhe foi atribuída responde 404, e uma ação ausente em uma conta atribuída responde 403.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—

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

Exemplo

bash

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

Ativar ou desativar uma conta de serviço

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

Acesso: Permissão de administração de serviços service-account.manage · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Define enabled; expectedRevision deve ser a revisão atual; caso contrário, 409 revision_mismatch. Somente este indicador muda aqui (o nome não pode ser alterado). Desativar bloqueia todas as chaves da conta a partir da próxima solicitação; ativar restaura as chaves que não expiraram nem foram revogadas. Um delegado só pode fazê-lo quando toda a política atual está dentro do seu teto.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`expectedRevision`	integer	sim	1–2147483646
`enabled`	boolean	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—

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

Exemplo

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

Obter a política de uma conta de serviço

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

Acesso: Permissão de administração de serviços policy.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna a conta com os bindings e a revision da sua política, como getServiceAccount, para um chamador que tem policy.read. As permissões efetivas de uma chave são a interseção desta política com os vínculos da própria chave, por repositório e ação.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—

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

Exemplo

bash

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

Substituir a política de uma conta de serviço

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

Acesso: Permissão de administração de serviços policy.manage · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Substitui os bindings da conta (até 64, cada um um repositório com suas ações exatas); expectedRevision deve ser a revisão atual; caso contrário, 409 revision_mismatch. Cada chave segue a mudança a partir da sua próxima solicitação: a restrição entra em vigor imediatamente, e a ampliação nunca vai além dos vínculos da própria chave. Um delegado precisa que tanto a política atual quanto a nova estejam dentro do seu teto.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`expectedRevision`	integer	sim	1–2147483646
`bindings`	array de object	sim	até 64 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`

Resposta 200

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—

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

Exemplo

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

Listar as chaves de uma conta de serviço

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

Acesso: Permissão de administração de serviços credential.read · Repetição: Pode ser repetida com segurança (leitura)

Lista os metadados das chaves da conta ordenados por ID, 50 por página: nome, state (pending, active, revoked), vínculos, criação, expiração, prazo de ativação e a chave da qual ela foi rotacionada; nunca segredos nem hashes. Continue com after definido como next. A expiração não altera state; portanto, compare expiresAt com a hora atual.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`after`	consulta	string (uuid)	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	sim	até 50 itens
`items[].id`	string (uuid)	sim	—
`items[].accountId`	string (uuid)	sim	—
`items[].name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`items[].state`	string	sim	um destes: `pending`, `active`, `revoked`
`items[].bindings`	array de object	sim	até 64 itens
`items[].bindings[].resource`	object	sim	—
`items[].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`
`items[].createdAt`	string (date-time)	sim	—
`items[].expiresAt`	string (date-time)	sim	—
`items[].activationExpiresAt`	string (date-time)	sim	—
`items[].rotatedFrom`	string (uuid)	sim	pode ser null
`next`	string (uuid)	sim	pode ser null

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

Exemplo

bash

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

Emitir uma chave para uma conta de serviço

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

Acesso: Permissão de administração de serviços credential.manage · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key

Emite uma chave pendente com name, bindings (efetivos apenas onde a política da conta também os permite) e expiresAt opcional (UTC; 90 dias por padrão, no máximo 365 e, para um delegado, nunca além da sua própria chave). A primeira resposta é 201 com key e o secret, exibido somente desta vez; uma repetição com o mesmo Idempotency-Key e o mesmo corpo é 200 apenas com os metadados, e um corpo diferente é 409. O titular deve chamar activateServiceKey com o segredo em até 15 minutos; se o segredo foi perdido, revogue a chave e emita uma nova com um novo Idempotency-Key.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`Idempotency-Key`	cabeçalho	string	sim	até 128 caracteres

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	array de object	sim	até 64 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`
`expiresAt`	string (date-time)	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`key`	object	sim	—
`key.id`	string (uuid)	sim	—
`key.accountId`	string (uuid)	sim	—
`key.name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	sim	um destes: `pending`, `active`, `revoked`
`key.bindings`	array de object	sim	até 64 itens
`key.bindings[].resource`	object	sim	—
`key.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`
`key.createdAt`	string (date-time)	sim	—
`key.expiresAt`	string (date-time)	sim	—
`key.activationExpiresAt`	string (date-time)	sim	—
`key.rotatedFrom`	string (uuid)	sim	pode ser null
`secret`	string	não	—

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

Exemplo

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

Ler a auditoria de uma conta de serviço

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

Acesso: Permissão de administração de serviços service-audit.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna, do mais antigo para o mais recente, até 100 eventos da conta após a sequência after (padrão 0): alterações de conta, de política e de chaves, como emissão, rotação, ativação e revogação, cada uma com ator, ação, chave e hora. Para ler mais, passe o último sequence como after; não existe o campo next. Somente os 100 000 eventos mais recentes do servidor são mantidos.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`after`	consulta	string	não	um número inteiro em dígitos decimais, enviado como string

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	sim	até 100 itens
`items[].sequence`	string	sim	—
`items[].actor`	string	sim	—
`items[].action`	string	sim	—
`items[].accountId`	string (uuid)	sim	—
`items[].keyId`	string (uuid)	sim	pode ser null
`items[].occurredAt`	string (date-time)	sim	—

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

Exemplo

bash

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

Obter uma chave

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

Acesso: Permissão de administração de serviços credential.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna os metadados de uma chave gerenciada: sua conta, nome, estado, vínculos, criação, expiração, prazo de ativação e a chave da qual foi rotacionada; nunca o segredo nem o seu hash.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`id`	string (uuid)	sim	—
`accountId`	string (uuid)	sim	—
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`state`	string	sim	um destes: `pending`, `active`, `revoked`
`bindings`	array de object	sim	até 64 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`
`createdAt`	string (date-time)	sim	—
`expiresAt`	string (date-time)	sim	—
`activationExpiresAt`	string (date-time)	sim	—
`rotatedFrom`	string (uuid)	sim	pode ser null

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

Exemplo

bash

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

Rotacionar uma chave

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

Acesso: Permissão de administração de serviços credential.manage · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key

Emite um sucessor pendente da chave id para a mesma conta, com os mesmos bindings ou mais restritos, respondendo como issueServiceKey: 201 com o secret de uso único, 200 apenas com os metadados em uma repetição com o mesmo Idempotency-Key. Depois que o sucessor é ativado, a chave antiga continua válida por no máximo mais 24 horas; revogue-a explicitamente quando a nova funcionar, mas somente depois que os jobs iniciados por ela terminarem. As delegações mantidas por uma chave de operador não são copiadas para o seu sucessor.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`Idempotency-Key`	cabeçalho	string	sim	até 128 caracteres

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	array de object	sim	até 64 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`
`expiresAt`	string (date-time)	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`key`	object	sim	—
`key.id`	string (uuid)	sim	—
`key.accountId`	string (uuid)	sim	—
`key.name`	string	sim	corresponde a `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	sim	um destes: `pending`, `active`, `revoked`
`key.bindings`	array de object	sim	até 64 itens
`key.bindings[].resource`	object	sim	—
`key.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`
`key.createdAt`	string (date-time)	sim	—
`key.expiresAt`	string (date-time)	sim	—
`key.activationExpiresAt`	string (date-time)	sim	—
`key.rotatedFrom`	string (uuid)	sim	pode ser null
`secret`	string	não	—

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

Exemplo

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

Revogar uma chave

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

Acesso: Permissão de administração de serviços credential.manage · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Revoga a chave definitivamente: sua próxima solicitação falha, enquanto um download já em andamento não é interrompido. Repetir tem sucesso com 204. As chaves que uma chave de operador revogada emitiu e que já foram ativadas continuam válidas; revogue-as separadamente.

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

bash

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

Ativar uma chave

POST /api/v1/auth/activate-key

Acesso: A chave emitida, antes ou depois da ativação · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Comprova que o titular recebeu uma chave recém-emitida: chame-o com essa chave como Authorization: Bearer em até 15 minutos após a emissão, e a chave se torna ativa (204). Repetir é seguro e não prorroga a expiração. Ativar uma chave rotacionada reduz o tempo de vida restante da chave que ela substitui para no máximo 24 horas.

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

Exemplo

bash

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

Listar as delegações de uma chave

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

Acesso: Chave de bootstrap ou a própria chave · Repetição: Pode ser repetida com segurança (leitura)

Retorna as delegações mantidas pela chave de operador id, até 64, inclusive as desativadas: para cada conta alvo, sua revision, se está enabled, as actions de administração (como credential.manage) e o ceiling de vínculos de repositório que ela pode repassar. Um delegado lê aqui as suas próprias (o ID da sua chave é credentialId em getOwnPermissions); a lista de outra chave gera 403.

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é 64 itens
`items[].keyId`	string (uuid)	sim	—
`items[].targetAccountId`	string (uuid)	sim	—
`items[].enabled`	boolean	sim	—
`items[].revision`	integer	sim	1–2147483647
`items[].actions`	array de string	sim	até 7 itens; sem itens repetidos; cada item: um destes: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`items[].ceiling`	array de object	sim	até 16 itens
`items[].ceiling[].resource`	object	sim	—
`items[].ceiling[].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`

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

Exemplo

bash

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

Delegar a administração de uma conta de serviço

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

Acesso: Chave de bootstrap (chave de recuperação da instalação) · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Permite que a chave id administre a conta de serviço accountId com as actions informadas (service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read) dentro do ceiling, até 16 vínculos de repositório que ela pode repassar; manage não implica read. expectedRevision é 0 para criar e a revisão atual do registro para alterá-lo ou reativá-lo; caso contrário, 409. A chave deve estar ativa e ter sido emitida pela chave de bootstrap, e uma conta não pode ao mesmo tempo manter delegações e ser alvo de uma, de modo que a delegação nunca se encadeia.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`accountId`	caminho	string (uuid)	sim	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`expectedRevision`	integer	sim	0–2147483646
`actions`	array de string	sim	1–7 itens; sem itens repetidos; cada item: um destes: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	array de object	sim	até 16 itens
`ceiling[].resource`	object	sim	—
`ceiling[].resource.kind`	string	sim	um destes: `repository`
`ceiling[].resource.id`	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].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`

Resposta 200

Campo	Tipo	Obrigatório	Regras
`keyId`	string (uuid)	sim	—
`targetAccountId`	string (uuid)	sim	—
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`actions`	array de string	sim	até 7 itens; sem itens repetidos; cada item: um destes: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	array de object	sim	até 16 itens
`ceiling[].resource`	object	sim	—
`ceiling[].resource.kind`	string	sim	um destes: `repository`
`ceiling[].resource.id`	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].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`

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

Exemplo

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

Retirar uma delegação

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

Acesso: Chave de bootstrap (chave de recuperação da instalação) · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Desativa a delegação da chave id sobre accountId; o corpo JSON traz expectedRevision, a revisão atual do registro. O registro permanece como uma entrada desativada, sem ações e com uma revisão maior, retornada com 200; após uma resposta perdida, leia-o com listServiceDelegations em vez de repetir, pois a revisão antiga gera 409. As chaves que o delegado já emitiu e ativou continuam funcionando: revogue-as ou desative a conta separadamente.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`id`	caminho	string (uuid)	sim	—
`accountId`	caminho	string (uuid)	sim	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`expectedRevision`	integer	sim	1–2147483646

Resposta 200

Campo	Tipo	Obrigatório	Regras
`keyId`	string (uuid)	sim	—
`targetAccountId`	string (uuid)	sim	—
`enabled`	boolean	sim	—
`revision`	integer	sim	1–2147483647
`actions`	array de string	sim	até 7 itens; sem itens repetidos; cada item: um destes: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	array de object	sim	até 16 itens
`ceiling[].resource`	object	sim	—
`ceiling[].resource.kind`	string	sim	um destes: `repository`
`ceiling[].resource.id`	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].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`

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

Exemplo

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

Contas de serviço e chaves ​

Operações ​

Listar contas de serviço ​

Criar uma conta de serviço ​

Obter uma conta de serviço ​

Ativar ou desativar uma conta de serviço ​

Obter a política de uma conta de serviço ​

Substituir a política de uma conta de serviço ​

Listar as chaves de uma conta de serviço ​

Emitir uma chave para uma conta de serviço ​

Ler a auditoria de uma conta de serviço ​

Obter uma chave ​

Rotacionar uma chave ​

Revogar uma chave ​

Ativar uma chave ​

Listar as delegações de uma chave ​

Delegar a administração de uma conta de serviço ​

Retirar uma delegação ​

Contas de serviço e chaves

Operações

Listar contas de serviço

Criar uma conta de serviço

Obter uma conta de serviço

Ativar ou desativar uma conta de serviço

Obter a política de uma conta de serviço

Substituir a política de uma conta de serviço

Listar as chaves de uma conta de serviço

Emitir uma chave para uma conta de serviço

Ler a auditoria de uma conta de serviço

Obter uma chave

Rotacionar uma chave

Revogar uma chave

Ativar uma chave

Listar as delegações de uma chave

Delegar a administração de uma conta de serviço

Retirar uma delegação