# Canonical API Surface

> Provide a complete entitlement and authorization setup path for iOS 16+ Screen Time apps, including distribution approval workflow.

- Skill: `tools-only/canonical-api-surface` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/canonical-api-surface`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/canonical-api-surface/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/canonical-api-surface

---

# 02 Authorization Setup

## Purpose
Provide a complete entitlement and authorization setup path for iOS 16+ Screen Time apps, including distribution approval workflow.

## Canonical API Surface
- Entitlement key: `com.apple.developer.family-controls`.
- Authorization API: `AuthorizationCenter.shared.requestAuthorization(for:)`.
- Status API: `AuthorizationCenter.authorizationStatus`.
- Member type: `FamilyControlsMember` (`individual`, `child`).

## Implementation Pattern
1. Register capability for **every relevant bundle ID**:
   - main app
   - DeviceActivity monitor extension
   - shield configuration extension
   - shield action extension
   - report extension (if used)
2. Add matching app group to every participating target.
3. Add `NSFamilyControlsUsageDescription` in app target info settings.
4. On first launch/onboarding, request authorization.
5. Re-check authorization at each enforcement boundary (app + extension).

## Entitlement Distribution Workflow
1. Request Family Controls distribution capability through Apple managed capability request flow.
2. Use official request endpoint:
   [Family Controls distribution request](https://developer.apple.com/contact/request/family-controls-distribution)
3. Wait for approval before production distribution.
4. Regenerate provisioning profiles after approval.
5. Validate Debug and Release both contain capability and correct entitlement file mapping.

## Waiting-Period Reality
- Observed in field reports and forum discussions: approval turnaround varies widely.
- Practical planning assumption:
  - best case: a few days
  - common case: multiple days to multiple weeks
- Treat capability approval as a critical release dependency and start early.

## Failure Modes
- Capability enabled only for app target, not extensions.
- Debug works, Release fails due to missing capability/profile refresh.
- Authorization denied/revoked but UI lacks recovery instructions.

## Validation Checklist
- [ ] Entitlement present in all required target entitlement files.
- [ ] `CODE_SIGN_ENTITLEMENTS` points to intended file for each build configuration.
- [ ] Usage description key is present in app build settings.
- [ ] App correctly handles `.notDetermined`, `.denied`, `.approved`.
- [ ] User-facing remediation path shown for deny/revoke.

## Sources
- https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.family-controls
- https://developer.apple.com/documentation/familycontrols/requesting-the-family-controls-entitlement
- https://developer.apple.com/documentation/xcode/configuring-family-controls
- https://developer.apple.com/contact/request/family-controls-distribution
- https://developer.apple.com/help/account/capabilities/capability-requests/
- `../evidence/01-familycontrols-sdk-signatures.md`
- `../evidence/07-claim-reconciliation.md`

## Confidence Notes
- Entitlement mechanics and authorization states are `canonical + sdk-backed`.
- Approval lead-time expectation is `field-note` and should be treated as risk planning guidance.