البدء السريع

خمسة طلبات: احصل على مفتاح، بادله برمز وصول، اسرد خزناتك، اسرد أسرار خزنة، واقرأ قيمة واحدة. كل مثال هنا يستخدم curl والأشكال الحقيقية الحالية — انسخ، الصق، وغيّر المعرّفات.

1. احصل على مفتاح API

في تطبيق OneGuard: Vault → API Keys → Add. اختر صلاحية القراءة أو الكتابة وتاريخ انتهاء، ثم انسخ المفتاح. يبدأ بـ og_ ويظهر مرة واحدة فقط.

2. بادله برمز وصول

لا تقبل الواجهة مفتاح og_... الخام في أي مكان سوى هذه النقطة الوحيدة.

curl -s https://api.oneguard.one/v1/auth/token \
  -X POST \
  -H "Authorization: Bearer og_your_key"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": {
    "access_token": "ogt_eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-09-23T15:04:05.000Z"
  }
}

احفظ data.access_token. صلاحيته 60 دقيقة — راجع المصادقة لمعرفة ماذا تفعل عند انتهائها.

3. اسرد خزناتك

كل طلب آخر يستخدم رمز الوصول، لا مفتاح API.

curl -s https://api.oneguard.one/v1/vaults \
  -H "Authorization: Bearer $TOKEN"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": [
    {
      "id": "429110bc-...",
      "org_id": "7a1c2e3f-...",
      "name": "My API",
      "icon_index": 4,
      "color": "#4F46E5",
      "team_id": null,
      "role": "admin",
      "created_at": "2026-01-15T10:20:30.000Z"
    }
  ],
  "next_cursor": null
}

data هي المصفوفة مباشرة؛ ويجلس next_cursor بجانبها. راجع شكل الاستجابة والتقسيم إلى صفحات لمعرفة كيفية تصفّح أكثر من شاشة واحدة من النتائج.

4. اسرد أسرار خزنة

curl -s https://api.oneguard.one/v1/vaults/429110bc-.../secrets \
  -H "Authorization: Bearer $TOKEN"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": [
    {
      "id": "3cb0cce2-...",
      "vault_id": "429110bc-...",
      "name": "production",
      "type": "env",
      "expired_at": null,
      "delete_after_expired": false,
      "is_archived": false,
      "created_at": "2026-02-01T09:00:00.000Z"
    }
  ],
  "next_cursor": null
}

هذه بيانات وصفية فقط — لا قيمة أبدًا، ولا حقول الأيقونة/اللون التي يستخدمها التطبيق لعرضه الخاص.

5. اقرأ قيمة سر

curl -s https://api.oneguard.one/v1/secrets/3cb0cce2-.../value \
  -H "Authorization: Bearer $TOKEN"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": {
    "id": "3cb0cce2-...",
    "vault_id": "429110bc-...",
    "name": "production",
    "type": "env",
    "expired_at": null,
    "delete_after_expired": false,
    "is_archived": false,
    "created_at": "2026-02-01T09:00:00.000Z",
    "value": {
      "DB_PASSWORD": "supersecret",
      "API_KEY": "sk_live_..."
    }
  }
}

تُفك تشفير القيمة من جهة الخادم لهذه الاستجابة الواحدة فقط، ولا تُخزَّن مؤقتًا أبدًا (Cache-Control: no-store على كل استجابة /v1).

إلى أين بعد ذلك

• المصادقة — مدة الرمز، وكيفية تجديده، وتدوير المفاتيح.
• شكل الاستجابة والتقسيم إلى صفحات — المغلّف، المؤشرات، الكتابات الآمنة عند التكرار.
• الأخطاء — كل رمز خطأ وكيفية التعامل مع 429.
• الخزنات والأسرار والفرق والمؤسسة وسجل التدقيق — المرجع الكامل لنقاط النهاية.