واجهة الأسرار (Secrets API)

أنشئ أسرار المشروع المشفّرة، واكشف قيمها وبدّلها واحذفها، واربطها بتطبيق عادي أو خدمة ويب أو معالجة خلفية أو افصلها عنه عبر الواجهة.

أدِر أسرار مشروعك المشفّرة عبر الواجهة: خزّن القيمة، واقرأها متى شئت، وبدّلها عند الحاجة (تدوير القيمة، rotation)، وأوصلها بتطبيق كمتغيّر بيئة (environment variable). لتجربة لوحة التحكم ومفاهيم المنتج (التشفير، الحدود، التسعير)، راجع الأسرار.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/secrets"

{
  "secrets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "value_size": 0,
      "value_version": 0,
      "attachments": [
        {
          "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
          "container_name": "string",
          "env_name": "DB_PASSWORD"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "project_name": "string",
      "attachment_count": 0
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

2-63 characters: lowercase letters, digits, and hyphens, starting and ending with a letter or digit. Doubles as the Kubernetes Secret data key once attached — validated as-is, never auto-normalized.

value*string

The plaintext value. 1-65536 bytes (64 KiB). Sealed at rest; never echoed back except by POST .../reveal.

description?string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets" \  -H "Content-Type: application/json" \  -d '{    "name": "db-password",    "value": "string"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets"

{
  "secrets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "value_size": 0,
      "value_version": 0,
      "attachments": [
        {
          "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
          "container_name": "string",
          "env_name": "DB_PASSWORD"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

At least one of value/description is required.

value?string

New plaintext value (1-65536 bytes). Omit to leave the value untouched.

description?string

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08/reveal"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "value": "string"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

containerId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

secret_id*string

env_name*string

Uppercase letters, digits, and underscores, starting with a letter or underscore (e.g. DB_PASSWORD). Must not already be set on the container, reserved by the platform, or used by another secret/service-link binding.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/containers/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets" \  -H "Content-Type: application/json" \  -d '{    "secret_id": "9e739c43-5a0b-4293-91b3-7c10894ec3f4",    "env_name": "DB_PASSWORD"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret_id": "9e739c43-5a0b-4293-91b3-7c10894ec3f4",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "env_name": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

containerId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/containers/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

الأخطاء تأتي برمز ورسالة

يُعيد كل طلب فاشل جسم JSON بالشكل { "code": "...", "message": "..." }. الرموز التي ستراها على نقاط النهاية هذه: 401 UNAUTHORIZED؛ 404 NOT_FOUND (السر أو المشروع أو التطبيق الذي لا تملكه يظهر كأنه غير موجود، دون أي تسريب)؛ 400 BAD_SECRET_NAME / 400 BAD_SECRET_VALUE (مخالفة قواعد الاسم أو حدّ القيمة 64 كيلوبايت)؛ 409 SECRET_NAME_TAKEN (الاسم مستخدم في المشروع بالفعل)؛ 409 SECRET_LIMIT_REACHED (الحد 100 سر لكل مشروع)؛ وعند الربط: 400 BAD_ENV_NAME أو 409 ENV_NAME_TAKEN أو 409 SECRETS_TOO_LARGE (القيم المربوطة في المشروع ستتجاوز الحدّ الإجمالي)؛ 409 SECRET_IN_USE عند الحذف وما زالت روابط قائمة؛ 409 PROJECT_SUSPENDED على عمليات الكتابة أثناء تعليق المشروع؛ 503 SECRETS_UNAVAILABLE عندما يكون نظام الأسرار غير متاح؛ و502 SECRETS_SYNC_FAILED / 502 SECRET_ROTATION_NOT_APPLIED عندما تُحفظ التغييرات لكن يتعذّر إيصالها إلى التطبيقات العاملة بعد؛ أعد المحاولة عندها.

القيم لا تُقرأ إلا عبر الكشف

تُعيد نقاط نهاية العرض (list) والقراءة (get) البيانات الوصفية فقط: الاسم والحجم والإصدار والتطبيقات المربوطة بالسر، ولا تُعيد القيمة أبداً. القيمة تعود حصراً من POST .../secrets/{secretId}/reveal، وكل عملية كشف تُسجَّل في سجلّ نشاط المشروع.

الربط يحقن متغيّر بيئة

يستقبل POST .../containers/{containerId}/secrets حقلَي secret_id وenv_name (بصيغة UPPER_SNAKE_CASE، على ألّا يتعارض مع متغيّرات التطبيق الموجودة أو تلك التي تحقنها المنصّة). توصل المنصّة القيمة إلى التطبيق وتعيد تشغيله، فما على كودك إلا أن يقرأ متغيّر البيئة عند بدء التشغيل. أما DELETE .../containers/{containerId}/secrets/{secretId} فيُزيل المتغيّر مع إعادة النشر التالية للتطبيق.

التدوير يعيد تشغيل التطبيقات المربوطة

يرفع PATCH .../secrets/{secretId} مع قيمة value جديدة إصدارَ السر، ويعيد تلقائياً تشغيل كل تطبيق مربوط به؛ تُقرأ متغيّرات البيئة عند بدء العملية، فإعادة التشغيل هي ما يجعل القيمة الجديدة سارية. استجابة 502 SECRET_ROTATION_NOT_APPLIED تعني أن القيمة حُفظت لكن أحد التطبيقات المربوطة لم يلتقطها بعد؛ أعد استدعاء الطلب نفسه حتى ينجح.

واجهة الأسرار (Secrets API)

200application/json

401application/json

503application/json

201application/json

400application/json

401application/json

404application/json

409application/json

503application/json

200application/json

401application/json

404application/json

503application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

409application/json

502application/json

503application/json

204

401application/json

404application/json

409application/json

200application/json

401application/json

404application/json

503application/json

201application/json

400application/json

401application/json

404application/json

409application/json

502application/json

503application/json

204

401application/json

404

409application/json

502application/json

503application/json

في هذه الصفحة

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`