حسابات الخدمة والمفاتيح

حسابات الخدمة لأنظمة CI والأتمتة، ومفاتيحها، وسياساتها، وتفويضاتها، وتدقيقها.

عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).

العمليات

عرض قائمة حسابات الخدمة

GET HEAD /api/v1/service-accounts

الوصول: إذن إدارة الخدمات service-account.read · إعادة المحاولة: آمن للتكرار (قراءة)

يسرد حسابات الخدمة التي يجوز للمستدعي رؤيتها، مرتبةً حسب المعرّف، 50 في الصفحة، لكل منها الاسم وعلامة التفعيل وrevision وارتباطات السياسة bindings ووقت الإنشاء؛ وللمتابعة اضبط after على قيمة next. يرى مفتاح التهيئة (bootstrap) كلها، أما المفوَّض فيرى فقط الأهداف التي يتضمن تفويضه فيها service-account.read؛ ومن دون ذلك تكون القائمة فارغة لا مرفوضة.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`after`	الاستعلام	string (uuid)	لا	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`items`	مصفوفة من object	نعم	عدد العناصر: 50 كحد أقصى
`items[].id`	string (uuid)	نعم	—
`items[].name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`items[].enabled`	boolean	نعم	—
`items[].revision`	integer	نعم	1–2147483647
`items[].bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`items[].bindings[].resource`	object	نعم	—
`items[].bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`items[].createdAt`	string (date-time)	نعم	—
`next`	string (uuid)	نعم	يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

إنشاء حساب خدمة

POST /api/v1/service-accounts

الوصول: مفتاح التهيئة (مفتاح استرداد التثبيت) · إعادة المحاولة: لا تكرّره تلقائيًا

ينشئ هوية آلية لـ CI أو لتطبيق بـ name (من 3 إلى 64 حرفًا من الأحرف والأرقام أو _.-) وارتباطات سياسته bindings: لكل مستودع، الإجراءات الدقيقة التي يجوز لمفاتيحه استخدامها (مثل upload.create أو content.read). يردّ بـ 201 مع الحساب؛ ثم أصدر مفتاحًا بـ issueServiceKey. والاسم المأخوذ هو 409 already_exists.

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابة 201

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—

الاستجابات: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

bash

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

الحصول على حساب خدمة

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

الوصول: إذن إدارة الخدمات service-account.read · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد اسم الحساب وعلامة التفعيل وrevision وارتباطات السياسة ووقت الإنشاء. وبالنسبة للمفوَّض، فإن حسابًا لم يُسنَد إليه يعطي 404، وغياب إجراء على حساب مُسنَد إليه يعطي 403.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

تفعيل حساب خدمة أو تعطيله

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

الوصول: إذن إدارة الخدمات service-account.manage · إعادة المحاولة: لا تكرّره إلا مع المراجعة المتوقعة (compare-and-swap)

يعيّن enabled؛ ويجب أن تكون expectedRevision هي المراجعة الحالية، وإلا كانت النتيجة 409 revision_mismatch. لا يتغير هنا إلا هذه العلامة (أما الاسم فلا يتغير). يحجب التعطيل كل مفاتيح الحساب من الطلب التالي؛ ويعيد التفعيل المفاتيح التي لم تنتهِ صلاحيتها ولم تُبطل. ولا يجوز للمفوَّض ذلك إلا إذا كانت السياسة الحالية كلها ضمن سقفه (ceiling).

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`expectedRevision`	integer	نعم	1–2147483646
`enabled`	boolean	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

الحصول على سياسة حساب خدمة

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

الوصول: إذن إدارة الخدمات policy.read · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد الحساب مع ارتباطات سياسته bindings وrevision، مثل getServiceAccount، للمستدعي الذي يملك policy.read. الأذونات الفعلية للمفتاح هي تقاطع هذه السياسة مع ارتباطات المفتاح نفسه، لكل مستودع وإجراء.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

استبدال سياسة حساب خدمة

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

الوصول: إذن إدارة الخدمات policy.manage · إعادة المحاولة: لا تكرّره إلا مع المراجعة المتوقعة (compare-and-swap)

يستبدل bindings الحساب (حتى 64، كل منها مستودع مع إجراءاته الدقيقة)؛ ويجب أن تكون expectedRevision هي المراجعة الحالية، وإلا كانت النتيجة 409 revision_mismatch. يتبع كل مفتاح التغيير من طلبه التالي: التضييق يسري فورًا، والتوسيع لا يتجاوز أبدًا ارتباطات المفتاح نفسه. ويحتاج المفوَّض إلى أن تقع السياسة الحالية والجديدة معًا ضمن سقفه.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`expectedRevision`	integer	نعم	1–2147483646
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

عرض قائمة مفاتيح حساب خدمة

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

الوصول: إذن إدارة الخدمات credential.read · إعادة المحاولة: آمن للتكرار (قراءة)

يسرد بيانات تعريف مفاتيح الحساب مرتبةً حسب المعرّف، 50 في الصفحة: الاسم، وstate (pending أو active أو revoked)، والارتباطات، والإنشاء، والانتهاء، والمهلة النهائية للتفعيل، والمفتاح الذي دُوِّر هذا المفتاح منه؛ ولا تُعرض الأسرار ولا قيم التجزئة أبدًا. تابع بضبط after على قيمة next. لا يغيّر الانتهاء قيمة state، لذا قارن expiresAt بالوقت الحالي.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`after`	الاستعلام	string (uuid)	لا	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`items`	مصفوفة من object	نعم	عدد العناصر: 50 كحد أقصى
`items[].id`	string (uuid)	نعم	—
`items[].accountId`	string (uuid)	نعم	—
`items[].name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`items[].state`	string	نعم	إحدى القيم: `pending`, `active`, `revoked`
`items[].bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`items[].bindings[].resource`	object	نعم	—
`items[].bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`items[].createdAt`	string (date-time)	نعم	—
`items[].expiresAt`	string (date-time)	نعم	—
`items[].activationExpiresAt`	string (date-time)	نعم	—
`items[].rotatedFrom`	string (uuid)	نعم	يمكن أن يكون null
`next`	string (uuid)	نعم	يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

إصدار مفتاح لحساب خدمة

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

الوصول: إذن إدارة الخدمات credential.manage · إعادة المحاولة: آمن للتكرار مع Idempotency-Key نفسه

يصدر مفتاحًا معلّقًا بـ name وbindings (لا تسري إلا حيث تسمح بها سياسة الحساب أيضًا) وexpiresAt الاختياري (UTC؛ 90 يومًا افتراضيًا، و365 كحد أقصى، وبالنسبة للمفوَّض لا يتجاوز أجل مفتاحه هو). الردّ الأول 201 مع key وsecret اللذين يظهران هذه المرة فقط؛ وتكرار الطلب بـ Idempotency-Key والمتن نفسيهما يعطي 200 مع بيانات التعريف فقط، ومتن مختلف يعطي 409. على حامل المفتاح استدعاء activateServiceKey بالسر خلال 15 دقيقة؛ وإذا ضاع السر فأبطل المفتاح وأصدر مفتاحًا جديدًا بـ Idempotency-Key جديد.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`Idempotency-Key`	الترويسة	string	نعم	عدد الأحرف: 128 كحد أقصى

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`expiresAt`	string (date-time)	لا	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`key`	object	نعم	—
`key.id`	string (uuid)	نعم	—
`key.accountId`	string (uuid)	نعم	—
`key.name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	نعم	إحدى القيم: `pending`, `active`, `revoked`
`key.bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`key.bindings[].resource`	object	نعم	—
`key.bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`key.createdAt`	string (date-time)	نعم	—
`key.expiresAt`	string (date-time)	نعم	—
`key.activationExpiresAt`	string (date-time)	نعم	—
`key.rotatedFrom`	string (uuid)	نعم	يمكن أن يكون null
`secret`	string	لا	—

الاستجابات: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

قراءة تدقيق حساب خدمة

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

الوصول: إذن إدارة الخدمات service-audit.read · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد، بدءًا من الأقدم، ما يصل إلى 100 حدث للحساب بعد التسلسل after (الافتراضي 0): تغييرات الحساب والسياسة والمفاتيح، مثل الإصدار والتدوير والتفعيل والإبطال، لكل منها الفاعل والإجراء والمفتاح والوقت. وللمتابعة مرّر آخر sequence بوصفه after؛ ولا يوجد حقل next. لا يُحتفظ إلا بأحدث 100 000 حدث في الخادم.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`after`	الاستعلام	string	لا	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`items`	مصفوفة من object	نعم	عدد العناصر: 100 كحد أقصى
`items[].sequence`	string	نعم	—
`items[].actor`	string	نعم	—
`items[].action`	string	نعم	—
`items[].accountId`	string (uuid)	نعم	—
`items[].keyId`	string (uuid)	نعم	يمكن أن يكون null
`items[].occurredAt`	string (date-time)	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

الحصول على مفتاح

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

الوصول: إذن إدارة الخدمات credential.read · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد بيانات تعريف مفتاح مُدار واحد: حسابه واسمه وحالته وارتباطاته وإنشاءه وانتهاءه والمهلة النهائية لتفعيله والمفتاح الذي دُوِّر هذا المفتاح منه؛ ولا يعيد السر ولا قيمة تجزئته أبدًا.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`accountId`	string (uuid)	نعم	—
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`state`	string	نعم	إحدى القيم: `pending`, `active`, `revoked`
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`activationExpiresAt`	string (date-time)	نعم	—
`rotatedFrom`	string (uuid)	نعم	يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

تدوير مفتاح

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

الوصول: إذن إدارة الخدمات credential.manage · إعادة المحاولة: آمن للتكرار مع Idempotency-Key نفسه

يصدر خلفًا معلّقًا للمفتاح id للحساب نفسه بالارتباطات bindings نفسها أو بارتباطات أضيق، ويردّ مثل issueServiceKey: 201 مع secret لمرة واحدة، و200 مع بيانات التعريف فقط عند التكرار بـ Idempotency-Key نفسه. وبعد تفعيل الخلف يبقى المفتاح القديم صالحًا 24 ساعة أخرى كحد أقصى؛ فأبطله صراحةً عندما يعمل الجديد، لكن بعد انتهاء المهام التي بدأها فقط. ولا تُنسخ التفويضات التي يحملها مفتاح مشغّل (operator) إلى خلفه.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`Idempotency-Key`	الترويسة	string	نعم	عدد الأحرف: 128 كحد أقصى

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`bindings[].resource`	object	نعم	—
`bindings[].resource.kind`	string	نعم	إحدى القيم: `repository`
`bindings[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`expiresAt`	string (date-time)	لا	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`key`	object	نعم	—
`key.id`	string (uuid)	نعم	—
`key.accountId`	string (uuid)	نعم	—
`key.name`	string	نعم	يطابق النمط `^[a-zA-Z0-9_.-]{3,64}$`
`key.state`	string	نعم	إحدى القيم: `pending`, `active`, `revoked`
`key.bindings`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`key.bindings[].resource`	object	نعم	—
`key.bindings[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`
`key.createdAt`	string (date-time)	نعم	—
`key.expiresAt`	string (date-time)	نعم	—
`key.activationExpiresAt`	string (date-time)	نعم	—
`key.rotatedFrom`	string (uuid)	نعم	يمكن أن يكون null
`secret`	string	لا	—

الاستجابات: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

إبطال مفتاح

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

الوصول: إذن إدارة الخدمات credential.manage · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه

يبطل المفتاح نهائيًا: يفشل طلبه التالي، بينما لا يُقطع تنزيل قيد التشغيل. والتكرار ينجح بـ 204. أما المفاتيح التي أصدرها مفتاح مشغّل مُبطَل وتم تفعيلها بالفعل فتظل صالحة؛ فأبطلها على حدة.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابات: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

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

تفعيل مفتاح

POST /api/v1/auth/activate-key

الوصول: المفتاح الصادر، قبل التنشيط أو بعده · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه

يثبت أن الحامل تسلّم مفتاحًا أُصدر حديثًا: استدعِه بذلك المفتاح في Authorization: Bearer خلال 15 دقيقة من الإصدار، فيصبح المفتاح فعّالًا (204). والتكرار آمن ولا يمدّ مدة الانتهاء. وتفعيل مفتاح مُدوَّر يقصّر ما تبقى من عمر المفتاح الذي يحلّ محله إلى 24 ساعة كحد أقصى.

الاستجابات: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

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

عرض قائمة تفويضات مفتاح

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

الوصول: مفتاح التهيئة، أو المفتاح نفسه · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد التفويضات التي يحملها مفتاح المشغّل id، حتى 64 بما فيها المعطّلة: لكل حساب هدف revision الخاصة به، وما إذا كان enabled، وactions الإدارة (مثل credential.manage)، وceiling لارتباطات المستودعات التي يجوز له منحها. يقرأ المفوَّض تفويضاته هنا (ومعرّف مفتاحه هو credentialId في getOwnPermissions)؛ وقائمة مفتاح آخر هي 403.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`items`	مصفوفة من object	نعم	عدد العناصر: 64 كحد أقصى
`items[].keyId`	string (uuid)	نعم	—
`items[].targetAccountId`	string (uuid)	نعم	—
`items[].enabled`	boolean	نعم	—
`items[].revision`	integer	نعم	1–2147483647
`items[].actions`	مصفوفة من string	نعم	عدد العناصر: 7 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`items[].ceiling`	مصفوفة من object	نعم	عدد العناصر: 16 كحد أقصى
`items[].ceiling[].resource`	object	نعم	—
`items[].ceiling[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

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

تفويض إدارة حساب خدمة

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

الوصول: مفتاح التهيئة (مفتاح استرداد التثبيت) · إعادة المحاولة: لا تكرّره إلا مع المراجعة المتوقعة (compare-and-swap)

يتيح للمفتاح id إدارة حساب الخدمة accountId بالإجراءات actions المعطاة (service-account.read وservice-account.manage وpolicy.read وpolicy.manage وcredential.read وcredential.manage وservice-audit.read) ضمن ceiling، أي حتى 16 ارتباط مستودع يجوز له منحها؛ والإدارة (manage) لا تعني القراءة ضمنًا. تكون expectedRevision هي 0 للإنشاء، وهي المراجعة الحالية للسجل لتغييره أو إعادة تفعيله، وإلا كانت النتيجة 409. يجب أن يكون المفتاح فعّالًا وصادرًا عن مفتاح التهيئة، ولا يجوز لحساب أن يحمل تفويضات وأن يكون هدفًا لتفويض في آن واحد، فلا تتسلسل التفويضات أبدًا.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`accountId`	المسار	string (uuid)	نعم	—

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`expectedRevision`	integer	نعم	0–2147483646
`actions`	مصفوفة من string	نعم	عدد العناصر: 1–7; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	مصفوفة من object	نعم	عدد العناصر: 16 كحد أقصى
`ceiling[].resource`	object	نعم	—
`ceiling[].resource.kind`	string	نعم	إحدى القيم: `repository`
`ceiling[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`keyId`	string (uuid)	نعم	—
`targetAccountId`	string (uuid)	نعم	—
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`actions`	مصفوفة من string	نعم	عدد العناصر: 7 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	مصفوفة من object	نعم	عدد العناصر: 16 كحد أقصى
`ceiling[].resource`	object	نعم	—
`ceiling[].resource.kind`	string	نعم	إحدى القيم: `repository`
`ceiling[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

سحب تفويض

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

يعطّل تفويض المفتاح id على accountId؛ ويحمل متن JSON القيمة expectedRevision، وهي المراجعة الحالية للسجل. يبقى السجل مدخلًا معطّلًا بلا إجراءات وبمراجعة أعلى، ويُعاد مع 200؛ وبعد ضياع الردّ اقرأه بـ listServiceDelegations بدلًا من التكرار، لأن المراجعة القديمة تعطي 409. المفاتيح التي أصدرها المفوَّض وفعّلها بالفعل تواصل العمل: فأبطلها أو عطّل الحساب على حدة.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—
`accountId`	المسار	string (uuid)	نعم	—

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`expectedRevision`	integer	نعم	1–2147483646

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`keyId`	string (uuid)	نعم	—
`targetAccountId`	string (uuid)	نعم	—
`enabled`	boolean	نعم	—
`revision`	integer	نعم	1–2147483647
`actions`	مصفوفة من string	نعم	عدد العناصر: 7 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: `service-account.read`, `service-account.manage`, `policy.read`, `policy.manage`, `credential.read`, `credential.manage`, `service-audit.read`
`ceiling`	مصفوفة من object	نعم	عدد العناصر: 16 كحد أقصى
`ceiling[].resource`	object	نعم	—
`ceiling[].resource.kind`	string	نعم	إحدى القيم: `repository`
`ceiling[].resource.id`	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`ceiling[].actions`	مصفوفة من string	نعم	عدد العناصر: 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`

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

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

حسابات الخدمة والمفاتيح ​

العمليات ​

عرض قائمة حسابات الخدمة ​

إنشاء حساب خدمة ​

الحصول على حساب خدمة ​

تفعيل حساب خدمة أو تعطيله ​

الحصول على سياسة حساب خدمة ​

استبدال سياسة حساب خدمة ​

عرض قائمة مفاتيح حساب خدمة ​

إصدار مفتاح لحساب خدمة ​

قراءة تدقيق حساب خدمة ​

الحصول على مفتاح ​

تدوير مفتاح ​

إبطال مفتاح ​

تفعيل مفتاح ​

عرض قائمة تفويضات مفتاح ​

تفويض إدارة حساب خدمة ​

سحب تفويض ​

حسابات الخدمة والمفاتيح

العمليات

عرض قائمة حسابات الخدمة

إنشاء حساب خدمة

الحصول على حساب خدمة

تفعيل حساب خدمة أو تعطيله

الحصول على سياسة حساب خدمة

استبدال سياسة حساب خدمة

عرض قائمة مفاتيح حساب خدمة

إصدار مفتاح لحساب خدمة

قراءة تدقيق حساب خدمة

الحصول على مفتاح

تدوير مفتاح

إبطال مفتاح

تفعيل مفتاح

عرض قائمة تفويضات مفتاح

تفويض إدارة حساب خدمة

سحب تفويض