oauth

OAuth (MCP)

The Nest-routed, bearer-authed half of the OAuth 2.1 authorization flow (consent context + decision) — see the MCP & OAuth guide for the full flow including the raw RFC endpoints.

2 نقاط النهاية

GET `/api/v1/oauth/authorize/context`

Client name, scope description, and mcp.access-eligible tenants for the consent screen.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

معطيات المسار والاستعلام

الاسم	الموضع	النوع	القيود
clientIdمطلوب	query	string	≥1 chars
redirectUriمطلوب	query	string	≥1 chars
scopeمطلوب	query	string	≥1 chars

مثال بأمر curl

curl

curl -X GET "https://your-institute.example/api/v1/oauth/authorize/context?clientId=institflow-cli-a1b2c3&redirectUri=string&scope=string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200

الاسم	النوع	القيود
clientNameمطلوب	string	—
scopeمطلوب	string	—
membershipsمطلوب	array<object>	—

json

{
  "clientName": "string",
  "scope": "string",
  "memberships": [
    {
      "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
      "tenantSlug": "string",
      "tenantName": "string",
      "membershipId": "e34c26d7-e34c-734c-84c2-e34c26d7e34c"
    }
  ]
}

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

POST `/api/v1/oauth/authorize/decision`

Approve or deny an MCP client authorization request.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

محتوى الطلب

الاسم	النوع	القيود
clientIdمطلوب	string	≥1 chars
redirectUriمطلوب	string	≥1 chars
stateمطلوب	string	—
codeChallengeمطلوب	string	≥1 chars
codeChallengeMethodمطلوب	enum: "S256"	—
scopeمطلوب	string	≥1 chars
membershipId	string (uuid)	—
approveمطلوب	boolean	—

مثال

json

{
  "clientId": "institflow-cli-a1b2c3",
  "redirectUri": "string",
  "state": "string",
  "codeChallenge": "string",
  "codeChallengeMethod": "S256",
  "scope": "string",
  "membershipId": "e34c26d7-e34c-734c-84c2-e34c26d7e34c",
  "approve": true
}

مثال بأمر curl

curl

curl -X POST "https://your-institute.example/api/v1/oauth/authorize/decision" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "clientId": "institflow-cli-a1b2c3",
    "redirectUri": "string",
    "state": "string",
    "codeChallenge": "string",
    "codeChallengeMethod": "S256",
    "scope": "string",
    "membershipId": "e34c26d7-e34c-734c-84c2-e34c26d7e34c",
    "approve": true
  }'

الاستجابات

200

الاسم	النوع	القيود
redirectToمطلوب	string	—

json

{
  "redirectTo": "string"
}