Docs · Friends API · Cloudflare Pages Functions

Apple Music API

Catalog-only proxy for friends. Your app calls verantyx.ai; the edge holds the Apple developer token. Never share the .p8 private key.

Architecture

Friend app → https://verantyx.ai/api/apple-music/* (API key + developer JWT) → api.music.apple.com. Implemented as Cloudflare Pages Functions — not Next.js API routes (this site is a static export).

Security

Rotate FRIEND_API_KEYS if a key leaks. Never commit .p8 files or paste them into client apps. This proxy is catalog-only by default: search and metadata only. Playback and library APIs need a Music User Token from MusicKit on the user device — that token is not issued or stored here.

Endpoints

  • GET /api/apple-music/search — Query params: term (required), types (default songs,albums,artists), storefront (default us), optional limit (1–25), offset. Header: x-api-key.
  • GET /api/apple-music/health — Public. Confirms the service is up and whether credentials are configured — never returns secrets.

Rate limits

60 requests per API key per rolling 60-second window, counted in-memory per Cloudflare isolate (not a global edge-wide counter). Responses include X-RateLimit-* headers; 429 includes Retry-After.

Example curl

Search
curl -sS "https://verantyx.ai/api/apple-music/search?term=beatles&types=songs,albums&storefront=us" \
  -H "x-api-key: YOUR_FRIEND_API_KEY"
Health
curl -sS "https://verantyx.ai/api/apple-music/health"

Cloudflare secrets

Pages → your project → Settings → Environment variables (Production). Mark secrets as encrypted. Set:

  • APPLE_TEAM_ID
  • APPLE_MUSIC_KEY_ID
  • APPLE_MUSIC_PRIVATE_KEY
  • FRIEND_API_KEYS

For APPLE_MUSIC_PRIVATE_KEY, paste the full PEM. Newlines may be stored as \n. See .env.example in the repo. Never commit real .p8 files.

Local test

wrangler
cp .env.example .dev.vars
# edit .dev.vars with real values (gitignored)

npm run build
npx wrangler pages dev out --compatibility-date=2026-07-15

curl -sS "http://127.0.0.1:8788/api/apple-music/health"
curl -sS "http://127.0.0.1:8788/api/apple-music/search?term=beatles&types=songs&storefront=us" \
  -H "x-api-key: friend-key-one"

Music User Token

Developer tokens authorize catalog access. User-specific playback, library, and recommendations require a Music User Token from Apple MusicKit JS / native MusicKit after the user signs in. Do not send user tokens to this proxy unless you intentionally extend it — today it only attaches the server developer JWT.