API Documentation
REST API for mobile and third-party clients. Base URL: https://audio.gospelpublishers.com/api
Overview
The API supports:
- Bearer token authentication (Sanctum)
- OAuth: Google and Apple SSO via
/api/auth/{provider}and callback - HLS streaming with AES-128 key delivery for protected audiobooks
- Books, purchases, listening progress, and audiobook catalog
Authentication
POST /api/auth/login
Email/password login. Returns short-lived Bearer token (1 hour).
Request body:
{"email": "user@example.com", "password": "secret"}Response 200:
{"access_token": "2|...", "token_type": "bearer", "expires_in": 3600}Response 401:
{"message": "Invalid credentials"}GET /api/auth/{provider} | GET /api/auth/{provider}/callback
Providers: google, apple. Redirect user to /api/auth/{provider}; after authorization they hit the callback. Callback returns JSON: user, token, token_type (Bearer).
POST /api/auth/refresh · Requires:
Authorization: Bearer <token>Returns new access_token and expires_in (same shape as login).
POST /api/auth/logout · Requires: Bearer
Revokes the current token.
GET /api/user · Requires: Bearer
Returns the authenticated user (with roles/permissions).
Public Endpoints
- POST /api/register — Register (body: name, email, password, password_confirmation)
- POST /api/login — Login (returns token; same as /api/auth/login shape)
- GET /api/books — List books (paginated)
- GET /api/books/{id} — Single book detail
- GET /api/search?q= — Search books
Audiobooks (Protected)
All require Authorization: Bearer <token>. Returns catalog for the authenticated user (purchased titles).
- GET /api/audiobooks — List user's audiobooks (with chapters, HLS URL, etc.)
- GET /api/audiobooks/{id} — Single audiobook detail
- POST /api/audiobooks/{id}/download-token — Short-lived signed key URL for background downloads. Response:
download_key_url,expires_at.
HLS Key Delivery
GET /api/keys/{key_id} · Requires: Bearer (or dtoken query param for download URLs)
Returns raw 16-byte binary AES-128 key. Content-Type: application/octet-stream, Content-Length: 16. Validates that the user has access to the audiobook. Rate limited.
401 = invalid/missing token; 403 = no access; 404 = key not found.
Purchases & Listening Progress
All require Bearer token.
- POST /api/books/{book}/purchase — Create payment intent (Stripe). Optional JSON body:
redemption_codefor a book-scoped promo (free grant or discounted amount). - POST /api/purchases/confirm — Confirm purchase after payment
- GET /api/purchases — List user's purchases
- GET /api/listening-progress/{chapter} — Get progress for a chapter
- POST /api/listening-progress — Create/update progress (body: chapter_id, position_seconds, completed)
- PUT /api/listening-progress/{chapter} — Update progress
- GET /api/listening-progress/book/{bookId} — Progress for all chapters of a book
Summary of Endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/auth/login | — | Get Bearer token |
| GET | /api/auth/{provider} | — | OAuth redirect (google, apple) |
| GET | /api/auth/{provider}/callback | — | OAuth callback, returns token |
| POST | /api/auth/refresh | Bearer | Refresh token |
| POST | /api/auth/logout | Bearer | Revoke token |
| GET | /api/user | Bearer | Current user |
| GET | /api/books | — | List books |
| GET | /api/audiobooks | Bearer | User's audiobooks |
| GET | /api/audiobooks/{id} | Bearer | Audiobook detail |
| POST | /api/audiobooks/{id}/download-token | Bearer | Download key URL |
| GET | /api/keys/{key_id} | Bearer / dtoken | AES-128 key (16 bytes) |
| GET | /api/listening-progress/book/{bookId} | Bearer | Book progress |