本文へスキップ

アカウントとサインイン ​

サインイン、セッション、個人用アクセストークン、ユーザー、グループ、セキュリティ監査。

このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます:Authorization: Bearer <key>(「認証」を参照)。

操作 ​

サインイン ​

POST /api/v1/auth/login

アクセス: 誰でも(キー不要) · 再試行: 自動的に再試行しない

アカウントのnameとpasswordを、12時間有効なBearerセッションtokenと交換します。応答にはexpiresAtとアカウントも含まれ、トークンはAuthorization: Bearerとして送信します。未知の名前、誤ったパスワード、無効化されたアカウントは、いずれも同じ401 invalid_credentialsで応答します。試行はクライアントアドレスごと、アカウントごとに制限され(Retry-After付きの429 rate_limited)、1つのアカウントが保持できるセッションは最大32個で、新しいセッションを作ると最も古いものが終了します。

リクエスト本文 (application/json)

フィールド型必須ルール
namestringはい—
passwordstring (password)はい—

レスポンス 200

フィールド型必須ルール
tokenstringはい—
expiresAtstring (date-time)はい—
accountobjectはい—
account.idstring (uuid)はい—
account.namestringはい—
account.administratorbooleanはい—
account.enabledbooleanはい—

レスポンス: 200, 400, 401, 403, 405, 413, 415, 429, 503

例

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

アカウントの登録 ​

POST /api/v1/auth/register

アクセス: 誰でも(キー不要) · 再試行: 自動的に再試行しない

name(英字、数字、_.-からなる3〜64文字)とpassword(12〜128文字)で通常のアカウント(管理者ではありません)を作成してサインインさせ、loginと同様に12時間のセッションを付けて201で応答します。サーバーが自己登録を許可している場合(getAuthOptionsを参照)にのみ動作し、許可していない場合は403 registration_disabledになります。すでに使われている名前は409 already_existsです。試行はクライアントアドレスごとに制限され(Retry-After付きの429)、自己登録は900アカウントで停止します。

リクエスト本文 (application/json)

フィールド型必須ルール
namestringはい—
passwordstring (password)はい—

レスポンス 201

フィールド型必須ルール
tokenstringはい—
expiresAtstring (date-time)はい—
accountobjectはい—
account.idstring (uuid)はい—
account.namestringはい—
account.administratorbooleanはい—
account.enabledbooleanはい—

レスポンス: 201, 400, 403, 405, 413, 415, 429, 503

例

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

サインインオプションの取得 ​

GET HEAD /api/v1/auth/options

アクセス: 誰でも(キー不要) · 再試行: 再試行しても安全(読み取り)

サインイン前のコンソールに、どのフォームを表示するかを伝えます。このサーバーでregisterAccountが利用できる場合、selfRegistrationはtrueです。

レスポンス 200

フィールド型必須ルール
selfRegistrationbooleanはい—

レスポンス: 200, 400, 403, 503

例

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

個人用アクセストークンの一覧表示 ​

GET HEAD /api/v1/auth/tokens

アクセス: サインイン済みのアカウントセッション(キーは不可) · 再試行: 再試行しても安全(読み取り)

サインイン中のアカウントの個人用アクセストークンを、有効なものを先に列挙します。各項目には、名前、プレフィックス、スコープ、作成日時、有効期限、最終使用日時、取り消し済みかどうかが含まれます。シークレットが再び表示されることはありません。

レスポンス 200

フィールド型必須ルール
itemsobjectの配列はい100個以内の要素
items[].idstring (uuid)はい—
items[].namestringはい—
items[].prefixstringはい—
items[].scopestringはい次のいずれか:read, read-write
items[].createdAtstring (date-time)はい—
items[].expiresAtstring (date-time)いいえnullも可
items[].lastUsedAtstring (date-time)いいえnullも可
items[].revokedbooleanはい—

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

個人用アクセストークンの作成 ​

POST /api/v1/auth/tokens

アクセス: サインイン済みのアカウントセッション(キーは不可) · 再試行: 自動的に再試行しない

サインイン中のアカウントとして動作する、スクリプトやツール向けのトークンを作成します。シークレットはこの応答にのみ含まれます。nameは1〜64文字、expiresAtの既定は90日後で、未来かつ365日以内でなければなりません。scopeはread-write(既定)またはreadで、readでは何も変更できません。トークンに管理者権限が付くことはなく、トークンを作成することもできません。1つのアカウントが持てる有効なトークンは最大50個です(507 token_limit)。

リクエスト本文 (application/json)

フィールド型必須ルール
namestringはい—
expiresAtstring (date-time)いいえ—
scopestringいいえ次のいずれか:read, read-write

レスポンス 201

フィールド型必須ルール
idstring (uuid)はい—
namestringはい—
prefixstringはい—
scopestringはい次のいずれか:read, read-write
createdAtstring (date-time)はい—
expiresAtstring (date-time)いいえnullも可
lastUsedAtstring (date-time)いいえnullも可
revokedbooleanはい—
tokenstringはい—

レスポンス: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

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

個人用アクセストークンの取り消し ​

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

アクセス: サインイン済みのアカウントセッション(キーは不可) · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

サインイン中のアカウントの個人用アクセストークンを1つ取り消します。以後、そのトークンを使ったリクエストは失敗します。すでに取り消されたトークンを取り消した場合も成功します。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

サインアウト ​

POST /api/v1/auth/logout

アクセス: 有効なキーまたはセッション · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

Authorizationで送信されたアカウントのセッションを終了します。そのトークンはただちに使えなくなります。他の認証情報(個人用トークンまたはサービスキー)では、204を返し、何も取り消しません。

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

自分のパスワードの変更 ​

POST /api/v1/auth/password

アクセス: サインイン済みのアカウントセッション(キーは不可) · 再試行: 自動的に再試行しない

currentPasswordを確認したうえでnewPassword(12〜128文字)を設定します。現在のパスワードが誤っている場合は401 current_password_invalidになり、サインインのバックオフに計上されます。成功すると、現在のセッションを含め、アカウントのすべてのセッションとすべての個人用アクセストークンが取り消されるため、改めてサインインしてください。

リクエスト本文 (application/json)

フィールド型必須ルール
currentPasswordstring (password)はい—
newPasswordstring (password)はい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 429, 503, 507

例

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 HEAD /api/v1/auth/me

アクセス: 有効なキーまたはセッション · 再試行: 再試行しても安全(読み取り)

認証情報の持ち主を返します。内容は、id、管理者かどうか、認証情報の種類(session、personal-token、service-key、file-key)、個人用トークンのスコープ、readまたはwriteアクセスを持つリポジトリです。サインイン中のユーザーを表示したり、リポジトリを選択したりするために使用します。マネージドサービスキーの正確な権限を調べるには、getOwnPermissionsを使用してください。

レスポンス 200

フィールド型必須ルール
idstringはい—
administratorbooleanはい—
credentialstringいいえ次のいずれか:session, personal-token, service-key, file-key
tokenScopestringいいえ次のいずれか:read, read-write
grantsobjectの配列はい—
grants[].repositorystringはい—
grants[].permissionsstringの配列はい各要素:次のいずれか:read, write

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

アカウントの一覧表示 ​

GET HEAD /api/v1/users

アクセス: 管理者 · 再試行: 再試行しても安全(読み取り)

すべてのユーザーアカウントを名前順に列挙します。各項目には、ID、名前、管理者フラグ、有効かどうかが含まれます。サーバーが保持できるアカウントは最大1000件です。

レスポンス 200

フィールド型必須ルール
itemsobjectの配列いいえ—
items[].idstring (uuid)はい—
items[].namestringはい—
items[].administratorbooleanはい—
items[].enabledbooleanはい—

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

アカウントの作成 ​

POST /api/v1/users

アクセス: 管理者 · 再試行: 自動的に再試行しない

name(英字、数字、_.-からなる3〜64文字)、password(12〜128文字)、administrator(既定はfalse)でアカウントを作成し、201でそれを返します。すでに使われている名前は409 already_existsで、サーバーが保持できるアカウントは最大1000件です(507 account_limit)。

リクエスト本文 (application/json)

フィールド型必須ルール
namestringはい—
passwordstring (password)はい—
administratorbooleanいいえ—

レスポンス 201

フィールド型必須ルール
idstring (uuid)はい—
namestringはい—
administratorbooleanはい—
enabledbooleanはい—

レスポンス: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

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

アカウントの有効化、無効化、パスワードのリセット ​

PATCH /api/v1/users/{id}

アクセス: 管理者 · 再試行: 自動的に再試行しない

アカウントのenabledを変更するか、新しいpasswordを設定するか、その両方を行います。ここでは管理者フラグは変更できません。無効化するとアカウントのすべてのセッションが終了し、無効のままの間はその個人用トークンも使えなくなります。パスワードをリセットすると、すべてのセッションが終了し、すべての個人用トークンが取り消されます。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—

リクエスト本文 (application/json)

フィールド型必須ルール
enabledbooleanいいえ—
passwordstring (password)いいえ—

レスポンス 200

フィールド型必須ルール
idstring (uuid)はい—
namestringはい—
administratorbooleanはい—
enabledbooleanはい—

レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

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

アカウントの個人用アクセストークンの一覧表示 ​

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

アクセス: 管理者 · 再試行: 再試行しても安全(読み取り)

任意のアカウントの個人用アクセストークンを、有効なものを先に列挙します。各項目には、名前、プレフィックス、スコープ、作成日時、有効期限、最終使用日時、取り消し状況が含まれます。シークレットは含まれません。アカウントを無効化またはリセットする前に、自動化の利用状況を確認するために使用します。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—

レスポンス 200

フィールド型必須ルール
itemsobjectの配列はい100個以内の要素
items[].idstring (uuid)はい—
items[].namestringはい—
items[].prefixstringはい—
items[].scopestringはい次のいずれか:read, read-write
items[].createdAtstring (date-time)はい—
items[].expiresAtstring (date-time)いいえnullも可
items[].lastUsedAtstring (date-time)いいえnullも可
items[].revokedbooleanはい—

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

アカウントの個人用アクセストークンの取り消し ​

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

アクセス: 管理者 · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

アカウントidの個人用アクセストークンを1つ取り消します。以後、そのトークンを使ったリクエストは失敗し、このイベントはセキュリティ監査に記録されます。すでに取り消されたトークンを取り消した場合も成功します。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—
tokenIdパスstring (uuid)はい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

アクセスグループの一覧表示 ​

GET HEAD /api/v1/access-groups

アクセス: 管理者 · 再試行: 再試行しても安全(読み取り)

すべてのアクセスグループを、所属するアカウントのIDとリポジトリへの付与(readまたはwrite)とともに列挙します。サーバーが保持できるのは、グループが最大100件、所属と付与がそれぞれ最大10,000件です。

レスポンス 200

フィールド型必須ルール
itemsobjectの配列いいえ—
items[].idstring (uuid)はい—
items[].namestringはい—
items[].membersstring (uuid)の配列はい—
items[].grantsobjectの配列はい—
items[].grants[].repositorystringはい—
items[].grants[].accessstringはい次のいずれか:read, write

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

アクセスグループの作成 ​

POST /api/v1/access-groups

アクセス: 管理者 · 再試行: 自動的に再試行しない

name(英字、数字、_.-からなる2〜64文字)で空のグループを作成し、201でそれを返します。すでに使われている名前は409 already_existsです。メンバーはaddGroupMemberで、リポジトリはsetGroupGrantで追加します。

リクエスト本文 (application/json)

フィールド型必須ルール
namestringはい—

レスポンス 201

フィールド型必須ルール
idstring (uuid)はい—
namestringはい—
membersstring (uuid)の配列はい—
grantsobjectの配列はい—
grants[].repositorystringはい—
grants[].accessstringはい次のいずれか:read, write

レスポンス: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

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

グループへのアカウントの追加 ​

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

アクセス: 管理者 · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

アカウントuserIdをグループのメンバーにします。そのアカウントは、次のリクエストからグループのリポジトリアクセスを得ます。すでにメンバーであるアカウントを追加しても何も変わりません。所属の合計は最大10,000件です(507 membership_limit)。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—
userIdパスstring (uuid)はい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

グループからのアカウントの削除 ​

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

アクセス: 管理者 · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

アカウントuserIdをグループから削除します。グループ経由で持っていたアクセスは、次のリクエストから失われます。メンバーでないアカウントを削除した場合も成功します。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—
userIdパスstring (uuid)はい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

グループへのリポジトリアクセスの付与 ​

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

アクセス: 管理者 · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

グループのメンバーに、repositoryへのaccess(readまたはwrite)を付与します。そのグループの以前の付与は置き換えられ、メンバーの次のリクエストから適用されます。リポジトリを別途作成する必要はなく、付与によってメンバーから見えるようになります。付与の合計は最大10,000件です(507 grant_limit)。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—
repositoryパスstringはい—

リクエスト本文 (application/json)

フィールド型必須ルール
accessstringはい次のいずれか:read, write

レスポンス: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

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

グループのリポジトリアクセスの削除 ​

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

アクセス: 管理者 · 再試行: 再試行しても安全:同じリクエストは同じ効果になる

repositoryに対するグループの付与を削除します。メンバーには、他のグループ経由で持つアクセスだけが残ります。存在しない付与を削除した場合も成功します。

パラメーター

名前場所型必須ルール
idパスstring (uuid)はい—
repositoryパスstringはい—

レスポンス: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

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

セキュリティ監査の取得 ​

GET HEAD /api/v1/security/audit

アクセス: 管理者 · 再試行: 再試行しても安全(読み取り)

サインイン、登録、アカウント、グループ、付与、パスワード、個人用アクセストークンの変更の、追記専用ジャーナルを新しい順に返します。各項目には、実行者、認証情報の種類、対象、結果、クライアントアドレスが含まれます。スロットリングされた試行はジャーナルに記録されません。ページにはlimit件(1〜100、既定は50)が含まれ、続きはafterにnextを設定して取得します。

パラメーター

名前場所型必須ルール
afterクエリstringいいえ10進数字で表した整数(文字列として送信)
limitクエリintegerいいえ1~100

レスポンス 200

フィールド型必須ルール
itemsobjectの配列はい100個以内の要素
items[].idstringはい10進数字で表した整数(文字列として送信)
items[].occurredAtstring (date-time)はい—
items[].actorstringはいnullも可
items[].credentialstringはい次のいずれか:session, personal-token, service-key, file-key; nullも可
items[].clientIpstringはいnullも可
items[].actionstringはい—
items[].targetstringはいnullも可
items[].outcomestringはい次のいずれか:success, failure, denied
items[].codestringはいnullも可
items[].detailsobjectはい—
nextstringはいnullも可

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

自分の有効な権限の取得 ​

GET HEAD /api/v1/auth/permissions

アクセス: 有効なキーまたはセッション · 再試行: 再試行しても安全(読み取り)

呼び出し元のprofile(マネージドサービスキーではmanaged、それ以外はlegacy)、そのキーID、有効なバインディング(各リポジトリと、そこで許可される正確なアクション)、そしてブートストラップサービス管理者かどうかを返します。クライアントを適応させるために使用してください。サーバーはすべてのリクエストを引き続き確認するため、権限の変更はただちに反映されます。

レスポンス 200

フィールド型必須ルール
idstringはい—
profilestringはい次のいずれか:legacy, managed
bindingsobjectの配列はい10000個以内の要素
bindings[].resourceobjectはい—
bindings[].resource.kindstringはい次のいずれか:repository
bindings[].resource.idstringはい^[a-z0-9][a-z0-9_-]{0,63}$に一致
bindings[].actionsstringの配列はい1~24個の要素; 要素の重複なし; 各要素:次のいずれか: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
serviceAdministrationbooleanはい—
credentialIdstring (uuid)いいえnullも可

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

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

Arkvory · ProAnimaStudio