Accounts and sign-in

Sign-in, sessions, personal access tokens, users, groups and the security audit.

Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).

Operations

POST /api/v1/auth/login

Access: Anyone, without a key · Retry: Do not repeat automatically

Exchanges an account name and password for a bearer session token valid for 12 hours, with its expiresAt and the account; send it as Authorization: Bearer. An unknown name, a wrong password and a disabled account all answer the same 401 invalid_credentials. Attempts are throttled per client address and per account (429 rate_limited with Retry-After), and an account keeps at most 32 sessions: a new one ends the oldest.

Request body (application/json)

Field	Type	Required	Rules
`name`	string	yes	—
`password`	string (password)	yes	—

Response 200

Field	Type	Required	Rules
`token`	string	yes	—
`expiresAt`	string (date-time)	yes	—
`account`	object	yes	—
`account.id`	string (uuid)	yes	—
`account.name`	string	yes	—
`account.administrator`	boolean	yes	—
`account.enabled`	boolean	yes	—

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

Example

bash

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

Register an account

POST /api/v1/auth/register

Access: Anyone, without a key · Retry: Do not repeat automatically

Creates an ordinary account (never an administrator) with name (3–64 letters, digits or _.-) and password (12–128 characters) and signs it in, answering 201 with a 12-hour session like login. Works only when the server allows self-registration (see getAuthOptions), otherwise 403 registration_disabled; a taken name is a 409 already_exists. Attempts are throttled per client address (429 with Retry-After), and self-registration stops at 900 accounts.

Request body (application/json)

Field	Type	Required	Rules
`name`	string	yes	—
`password`	string (password)	yes	—

Response 201

Field	Type	Required	Rules
`token`	string	yes	—
`expiresAt`	string (date-time)	yes	—
`account`	object	yes	—
`account.id`	string (uuid)	yes	—
`account.name`	string	yes	—
`account.administrator`	boolean	yes	—
`account.enabled`	boolean	yes	—

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

Example

bash

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

Get the sign-in options

GET HEAD /api/v1/auth/options

Access: Anyone, without a key · Retry: Safe to repeat (read)

Tells a console before sign-in which forms to show: selfRegistration is true when registerAccount is open on this server.

Response 200

Field	Type	Required	Rules
`selfRegistration`	boolean	yes	—

Responses: 200, 400, 403, 503

Example

bash

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

List your personal access tokens

GET HEAD /api/v1/auth/tokens

Access: A signed-in account session (not a key) · Retry: Safe to repeat (read)

Lists the personal access tokens of the signed-in account, active first, with name, prefix, scope, creation, expiry, last use and whether it is revoked; the secrets are never shown again.

Response 200

Field	Type	Required	Rules
`items`	array of object	yes	up to 100 items
`items[].id`	string (uuid)	yes	—
`items[].name`	string	yes	—
`items[].prefix`	string	yes	—
`items[].scope`	string	yes	one of `read`, `read-write`
`items[].createdAt`	string (date-time)	yes	—
`items[].expiresAt`	string (date-time)	no	may be null
`items[].lastUsedAt`	string (date-time)	no	may be null
`items[].revoked`	boolean	yes	—

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

Example

bash

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

Create a personal access token

POST /api/v1/auth/tokens

Access: A signed-in account session (not a key) · Retry: Do not repeat automatically

Creates a token for scripts and tools that acts as the signed-in account; the secret is in this answer only. name has 1–64 characters, expiresAt defaults to 90 days and must lie in the future and within 365 days, and scope is read-write (default) or read, which can never change anything. Tokens never carry administrator rights, cannot create tokens, and an account has at most 50 active ones (507 token_limit).

Request body (application/json)

Field	Type	Required	Rules
`name`	string	yes	—
`expiresAt`	string (date-time)	no	—
`scope`	string	no	one of `read`, `read-write`

Response 201

Field	Type	Required	Rules
`id`	string (uuid)	yes	—
`name`	string	yes	—
`prefix`	string	yes	—
`scope`	string	yes	one of `read`, `read-write`
`createdAt`	string (date-time)	yes	—
`expiresAt`	string (date-time)	no	may be null
`lastUsedAt`	string (date-time)	no	may be null
`revoked`	boolean	yes	—
`token`	string	yes	—

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

Example

bash

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

Revoke your personal access token

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

Access: A signed-in account session (not a key) · Retry: Safe to repeat: the same request has the same effect

Revokes one personal access token of the signed-in account; requests with it fail from now on. Revoking an already revoked token succeeds as well.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—

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

Example

bash

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

Sign out

POST /api/v1/auth/logout

Access: Any valid key or session · Retry: Safe to repeat: the same request has the same effect

Ends the account session sent in Authorization; its token stops working at once. With any other credential (a personal token or a service key) it answers 204 and revokes nothing.

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

Example

bash

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

Change your password

POST /api/v1/auth/password

Access: A signed-in account session (not a key) · Retry: Do not repeat automatically

Sets newPassword (12–128 characters) after checking currentPassword; a wrong current password is a 401 current_password_invalid and counts toward the sign-in backoff. On success every session and every personal access token of the account is revoked, including the current session, so sign in again.

Request body (application/json)

Field	Type	Required	Rules
`currentPassword`	string (password)	yes	—
`newPassword`	string (password)	yes	—

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

Example

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

Get the current identity

GET HEAD /api/v1/auth/me

Access: Any valid key or session · Retry: Safe to repeat (read)

Returns who the credential belongs to: its id, whether it is an administrator, the credential kind (session, personal-token, service-key or file-key), the scope of a personal token, and the repositories it has read or write access to. Use it to show the signed-in user and to choose a repository; for the exact permissions of a managed service key use getOwnPermissions.

Response 200

Field	Type	Required	Rules
`id`	string	yes	—
`administrator`	boolean	yes	—
`credential`	string	no	one of `session`, `personal-token`, `service-key`, `file-key`
`tokenScope`	string	no	one of `read`, `read-write`
`grants`	array of object	yes	—
`grants[].repository`	string	yes	—
`grants[].permissions`	array of string	yes	each: one of `read`, `write`

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

Example

bash

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

List accounts

GET HEAD /api/v1/users

Access: Administrator · Retry: Safe to repeat (read)

Lists all user accounts ordered by name, with ID, name, administrator flag and whether they are enabled. The server holds at most 1000 accounts.

Response 200

Field	Type	Required	Rules
`items`	array of object	no	—
`items[].id`	string (uuid)	yes	—
`items[].name`	string	yes	—
`items[].administrator`	boolean	yes	—
`items[].enabled`	boolean	yes	—

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

Example

bash

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

Create an account

POST /api/v1/users

Access: Administrator · Retry: Do not repeat automatically

Creates an account with name (3–64 letters, digits or _.-), password (12–128 characters) and administrator (default false), and answers 201 with it. A taken name is a 409 already_exists; the server holds at most 1000 accounts (507 account_limit).

Request body (application/json)

Field	Type	Required	Rules
`name`	string	yes	—
`password`	string (password)	yes	—
`administrator`	boolean	no	—

Response 201

Field	Type	Required	Rules
`id`	string (uuid)	yes	—
`name`	string	yes	—
`administrator`	boolean	yes	—
`enabled`	boolean	yes	—

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

Example

bash

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

Enable, disable or reset an account

PATCH /api/v1/users/{id}

Access: Administrator · Retry: Do not repeat automatically

Changes enabled and/or sets a new password of an account; the administrator flag cannot be changed here. Disabling ends every session of the account and its personal tokens stop working while it stays disabled; a password reset ends every session and revokes every personal token.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—

Request body (application/json)

Field	Type	Required	Rules
`enabled`	boolean	no	—
`password`	string (password)	no	—

Response 200

Field	Type	Required	Rules
`id`	string (uuid)	yes	—
`name`	string	yes	—
`administrator`	boolean	yes	—
`enabled`	boolean	yes	—

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

Example

bash

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

List the personal access tokens of an account

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

Access: Administrator · Retry: Safe to repeat (read)

Lists the personal access tokens of any account, active first, with name, prefix, scope, creation, expiry, last use and revocation; never the secrets. Use it to review automation before disabling or resetting the account.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—

Response 200

Field	Type	Required	Rules
`items`	array of object	yes	up to 100 items
`items[].id`	string (uuid)	yes	—
`items[].name`	string	yes	—
`items[].prefix`	string	yes	—
`items[].scope`	string	yes	one of `read`, `read-write`
`items[].createdAt`	string (date-time)	yes	—
`items[].expiresAt`	string (date-time)	no	may be null
`items[].lastUsedAt`	string (date-time)	no	may be null
`items[].revoked`	boolean	yes	—

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

Example

bash

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

Revoke a personal access token of an account

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

Access: Administrator · Retry: Safe to repeat: the same request has the same effect

Revokes one personal access token of the account id; requests with it fail from now on, and the event is recorded in the security audit. Revoking an already revoked token succeeds as well.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—
`tokenId`	path	string (uuid)	yes	—

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

Example

bash

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

List access groups

GET HEAD /api/v1/access-groups

Access: Administrator · Retry: Safe to repeat (read)

Lists all access groups with their member account IDs and repository grants (read or write). The server holds at most 100 groups and 10 000 memberships and grants each.

Response 200

Field	Type	Required	Rules
`items`	array of object	no	—
`items[].id`	string (uuid)	yes	—
`items[].name`	string	yes	—
`items[].members`	array of string (uuid)	yes	—
`items[].grants`	array of object	yes	—
`items[].grants[].repository`	string	yes	—
`items[].grants[].access`	string	yes	one of `read`, `write`

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

Example

bash

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

Create an access group

POST /api/v1/access-groups

Access: Administrator · Retry: Do not repeat automatically

Creates an empty group with name (2–64 letters, digits or _.-) and answers 201 with it; a taken name is a 409 already_exists. Add members with addGroupMember and repositories with setGroupGrant.

Request body (application/json)

Field	Type	Required	Rules
`name`	string	yes	—

Response 201

Field	Type	Required	Rules
`id`	string (uuid)	yes	—
`name`	string	yes	—
`members`	array of string (uuid)	yes	—
`grants`	array of object	yes	—
`grants[].repository`	string	yes	—
`grants[].access`	string	yes	one of `read`, `write`

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

Example

bash

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

Add an account to a group

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

Access: Administrator · Retry: Safe to repeat: the same request has the same effect

Makes the account userId a member of the group; it gains the group's repository access with its next request. Adding an existing member changes nothing; at most 10 000 memberships in all (507 membership_limit).

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—
`userId`	path	string (uuid)	yes	—

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

Example

bash

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

Remove an account from a group

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

Access: Administrator · Retry: Safe to repeat: the same request has the same effect

Removes the account userId from the group; the access it had through the group ends with its next request. Removing an account that is not a member succeeds as well.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—
`userId`	path	string (uuid)	yes	—

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

Example

bash

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

Grant a group access to a repository

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

Access: Administrator · Retry: Safe to repeat: the same request has the same effect

Gives the group's members access read or write to repository, replacing an earlier grant of the group there; it applies from their next request. A repository needs no separate creation: the grant makes it visible to them. At most 10 000 grants in all (507 grant_limit).

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—
`repository`	path	string	yes	—

Request body (application/json)

Field	Type	Required	Rules
`access`	string	yes	one of `read`, `write`

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

Example

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

Remove a group's access to a repository

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

Access: Administrator · Retry: Safe to repeat: the same request has the same effect

Removes the group's grant for repository; its members keep only the access they have through other groups. Removing a grant that does not exist succeeds as well.

Parameters

Name	In	Type	Required	Rules
`id`	path	string (uuid)	yes	—
`repository`	path	string	yes	—

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

Example

bash

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

Read the security audit

GET HEAD /api/v1/security/audit

Access: Administrator · Retry: Safe to repeat (read)

Returns the append-only journal of sign-ins, registrations, account, group, grant, password and personal token changes, newest first, each with actor, credential kind, target, outcome and client address; throttled attempts are not journaled. Pages hold limit entries (1–100, default 50); continue with after set to next.

Parameters

Name	In	Type	Required	Rules
`after`	query	string	no	a whole number in decimal digits, sent as a string
`limit`	query	integer	no	1–100

Response 200

Field	Type	Required	Rules
`items`	array of object	yes	up to 100 items
`items[].id`	string	yes	a whole number in decimal digits, sent as a string
`items[].occurredAt`	string (date-time)	yes	—
`items[].actor`	string	yes	may be null
`items[].credential`	string	yes	one of `session`, `personal-token`, `service-key`, `file-key`; may be null
`items[].clientIp`	string	yes	may be null
`items[].action`	string	yes	—
`items[].target`	string	yes	may be null
`items[].outcome`	string	yes	one of `success`, `failure`, `denied`
`items[].code`	string	yes	may be null
`items[].details`	object	yes	—
`next`	string	yes	may be null

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

Example

bash

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

Get your effective permissions

GET HEAD /api/v1/auth/permissions

Access: Any valid key or session · Retry: Safe to repeat (read)

Returns the caller's profile (managed for a managed service key, legacy otherwise), its key ID, its effective bindings (each repository with the exact actions allowed there) and whether it is the bootstrap service administrator. Use it to adapt a client; the server still checks every request, so a change of permissions applies at once.

Response 200

Field	Type	Required	Rules
`id`	string	yes	—
`profile`	string	yes	one of `legacy`, `managed`
`bindings`	array of object	yes	up to 10000 items
`bindings[].resource`	object	yes	—
`bindings[].resource.kind`	string	yes	one of `repository`
`bindings[].resource.id`	string	yes	matches `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	array of string	yes	1–24 items; no repeated items; each: one of `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	yes	—
`credentialId`	string (uuid)	no	may be null

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

Example

bash

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

Accounts and sign-in ​

Operations ​

Sign in ​

Register an account ​

Get the sign-in options ​

List your personal access tokens ​

Create a personal access token ​

Revoke your personal access token ​

Sign out ​

Change your password ​

Get the current identity ​

List accounts ​

Create an account ​

Enable, disable or reset an account ​

List the personal access tokens of an account ​

Revoke a personal access token of an account ​

List access groups ​

Create an access group ​

Add an account to a group ​

Remove an account from a group ​

Grant a group access to a repository ​

Remove a group's access to a repository ​

Read the security audit ​

Get your effective permissions ​

Accounts and sign-in

Operations

Sign in

Register an account

Get the sign-in options

List your personal access tokens

Create a personal access token

Revoke your personal access token

Sign out

Change your password

Get the current identity

List accounts

Create an account

Enable, disable or reset an account

List the personal access tokens of an account

Revoke a personal access token of an account

List access groups

Create an access group

Add an account to a group

Remove an account from a group

Grant a group access to a repository

Remove a group's access to a repository

Read the security audit

Get your effective permissions