# 4. Public API & Webhooks

User Type: **Super Administrator**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 4. Public API & Webhooks

### 4.1 API Key Management
**What it does:** Issues, rotates, revokes, and scopes API keys for external developers and partners.
**Sub-features:**
- Key issuance (per developer/partner, with description).
- Key scoping (read, write, admin; per resource).
- Key rotation (generate new, deprecate old with grace period).
- Key revocation (immediate, scheduled).
- Key usage summary (requests, last used, status).
- available on web
- event logging (action performed)
- Audit logging of API key management
**Super Admin User Journey:**
1. Open Integrations & APIs → Public API → API Keys.
2. Issue a new key with a description and scopes.
3. Share the key with the developer (shown once).
4. Monitor usage and rotate or revoke as needed.
**Rules & Edge Cases:**
- A key is shown in full only once at creation; afterward only a masked prefix.
- A revoked key is rejected immediately on the next request.
- A rotated key's old key works until the grace period ends, then is rejected.
- A key with no scopes is rejected (at least one scope is required).
- A key exceeding its scope on a request receives a 403 and the attempt is logged.

### 4.2 Rate Limiting Configuration
**What it does:** Configures rate limits per API key, per endpoint, and per plan tier.
**Sub-features:**
- Global rate limit (requests per minute/hour).
- Per-key rate limit overrides.
- Per-endpoint rate limits (stricter for expensive endpoints).
- Per-plan-tier limits (higher tiers get higher limits).
- Rate limit headers and 429 response behavior.
- available on web
- event logging (action performed)
- Audit logging of rate limiting configuration
**Super Admin User Journey:**
1. Open Public API → Rate Limiting.
2. Set the global rate limit.
3. Define per-key and per-endpoint overrides.
4. Set the per-plan-tier limits.
5. Save and verify the limits apply.
**Rules & Edge Cases:**
- A request over the limit receives a 429 with a Retry-After header.
- A per-key override takes precedence over the global limit.
- A per-endpoint limit is stricter than (never looser than) the global limit.
- A plan-tier limit change applies to new requests immediately.
- A burst within the limit is allowed; sustained overage is throttled.

### 4.3 Webhook Event Configuration
**What it does:** Configures webhook events, endpoints, retries, and payload signing.
**Sub-features:**
- Event catalog (available events: enrollment, grade, payment, content).
- Endpoint registration (URL, per event or per event group).
- Retry policy (attempts, backoff, dead-letter).
- Payload signing (HMAC secret, signature header).
- Delivery log (status, latency, last success/failure).
- available on web
- event logging (action performed)
- Audit logging of webhook event configuration
**Super Admin User Journey:**
1. Open Public API → Webhooks.
2. Select the events to subscribe to.
3. Register the endpoint URL.
4. Configure the retry policy and generate the signing secret.
5. Send a test event and review the delivery log.
**Rules & Edge Cases:**
- A non-2xx response triggers a retry per the retry policy.
- A webhook that exhausts retries is moved to the dead-letter queue and flagged.
- A payload signature mismatch on the receiver side indicates a secret mismatch (documented).
- A webhook event is delivered at-least-once (receivers must be idempotent).
- An endpoint that is unreachable for a sustained period is marked down and alerted.

### 4.4 Embed Widgets
**What it does:** Provides embeddable widgets for partner sites (progress, schedule, announcements).
**Sub-features:**
- Widget catalog (progress, schedule, announcements, leaderboard).
- Widget configuration (theme, data scope, refresh interval).
- Embed code generation (script tag with token).
- Domain allowlist (which domains may embed).
- available on web
- event logging (action performed)
- Audit logging of embed widgets
**Super Admin User Journey:**
1. Open Public API → Embed Widgets.
2. Select a widget type and configure the theme and data scope.
3. Set the refresh interval.
4. Add allowed domains to the allowlist.
5. Generate the embed code and test it on an allowed domain.
**Rules & Edge Cases:**
- An embed on a non-allowlisted domain is blocked (widget shows an error state).
- A widget token is scoped to the configured data scope only.
- A widget refresh interval below the minimum is clamped to the minimum.
- A revoked widget token stops the widget from loading data.
- A widget never exposes data outside its configured scope.

### 4.5 Developer Documentation & Sandbox
**What it does:** Provides developer documentation and a sandbox environment for API testing.
**Sub-features:**
- API reference (endpoints, parameters, responses, errors).
- SDK and code samples (per language).
- Sandbox environment (isolated, test data, no production side effects).
- Sandbox key issuance (separate from production keys).
- Changelog (API version changes, deprecations).
- available on web
- event logging (action performed)
- Audit logging of developer documentation & sandbox
**Super Admin User Journey:**
1. Open Public API → Developer Docs.
2. Review the API reference and code samples.
3. Issue a sandbox key.
4. Test endpoints against the sandbox.
5. Publish documentation updates and changelog entries.
**Rules & Edge Cases:**
- A sandbox key cannot access production data (strictly isolated).
- A deprecated endpoint returns a deprecation header and a sunset date.
- A breaking API change requires a new version (old version kept until sunset).
- A sandbox reset clears test data and is logged.
- A documentation change is versioned and reflected in the changelog.