Overview
This guide helps developers understand the BeatPass technical environment, authentication model, and safe testing practices.
First-Party Only — BeatPass does not offer a public API for third-party applications. This documentation describes the API used by the official BeatPass applications.
Authentication Model
How Auth Works
BeatPass uses Laravel Sanctum for SPA (single-page application) authentication:
| Component | Implementation |
|---|
| Session auth | Cookie-based sessions |
| API tokens | Not issued (no bearer tokens) |
| Third-party integrations | Not supported |
| CSRF protection | Required for POST/PUT/DELETE |
Cookie + CSRF Flow
For web applications:
Get CSRF Cookie
This sets the XSRF-TOKEN cookie. Include CSRF Token
For POST/PUT/DELETE requests, include the token:X-XSRF-TOKEN: {token from cookie}
Authenticate
Submit credentials to the session login route shown in the Auth guide:POST /login
Content-Type: application/json
X-XSRF-TOKEN: {token from cookie}
{"email": "...", "password": "..."}
Make Authenticated Requests
Session cookies are automatically included in subsequent requests by the browser.
BeatPass does not issue Sanctum personal access tokens and does not support third-party integrations. Use the session-based fl
ow above.
Example Request Flow
Send credentials with the CSRF token, then rely on browser-managed cookies for later calls:
GET /sanctum/csrf-cookie
POST /login
Content-Type: application/json
X-XSRF-TOKEN: {token-from-cookie}
{"email": "[email protected]", "password": "secret"}
GET /tracks
# Cookies from the login response are sent automatically by the browser
Environment
No Public Sandbox
No Public Sandbox — BeatPass does not provide a public sandbox or test environment. All API calls hit production systems.
| Action | Impact |
|---|
| POST/PUT/DELETE requests | Real data is modified |
| Purchases | Real charges occur |
| Uploads | Real content is published |
| Messages | Real users receive messages |
Development Best Practices
| Practice | Why |
|---|
| Use personal test accounts | Avoid affecting real users |
| Test with minimal data | Don’t create spam content |
| Clean up test data | Delete test uploads promptly |
| Never test payments with real cards | Use Stripe test mode when available |
Testing Purchases
Stripe Test Mode
Contact your team lead to determine if Stripe test mode is enabled for your environment.
| Environment | Payment Behavior |
|---|
| Production | Real charges |
| Test mode (if enabled) | Stripe test cards accepted |
Test Card Numbers (Stripe Test Mode Only)
If test mode is available:
| Card Number | Behavior |
|---|
4242 4242 4242 4242 | Succeeds |
4000 0000 0000 0002 | Declines |
4000 0000 0000 9995 | Insufficient funds |
Never use test card numbers on production. They will fail and may flag your account.
Using Placeholder IDs
When developing or documenting:
Recommended Placeholders
| Entity | Placeholder Format | Example |
|---|
| Track ID | {track_id} | /tracks/{track_id} |
| User ID | {user_id} | /users/{user_id} |
| Artist ID | {artist_id} | /artists/{artist_id} |
| Album ID | {album_id} | /albums/{album_id} |
In Code Examples
// Good - uses placeholder
const trackId = process.env.TEST_TRACK_ID || '{track_id}';
// Bad - hardcodes production ID
const trackId = 12345;
In Documentation
GET /api/v1/tracks/{track_id}
Restricted Access
Administrative and internal endpoints are not documented here. These routes require elevated privileges and are protected by role-based access control. Unauthorized access attempts are logged and may result in account termination.
Safe API Usage
- Use documented endpoints only
- Respect rate limits
- Handle errors gracefully
- Clean up test data
- Log responsibly (no sensitive data)
Don’t
- Scrape or crawl the platform
- Hammer endpoints with excessive requests
- Store user credentials
- Bypass authentication
- Share API tokens
Error Handling
{
"message": "Human-readable error",
"errors": {
"field": ["Validation error message"]
}
}
HTTP Status Codes
| Code | Meaning | Action |
|---|
| 200 | Success | Process response |
| 201 | Created | Resource created |
| 400 | Bad Request | Fix request format |
| 401 | Unauthorized | Re-authenticate |
| 403 | Forbidden | Check permissions |
| 404 | Not Found | Resource doesn’t exist |
| 422 | Validation Error | Fix input data |
| 429 | Rate Limited | Back off and retry |
| 500 | Server Error | Report to support |
Getting Help
| Topic | Contact |
|---|
| API questions | [email protected] |
| Security concerns | [email protected] |
| Partnership inquiries | [email protected] |
Documentation
Checklist for New Developers
Get Access
- Obtain development account credentials
- Set up local environment
- Understand the session-based auth flow
Understand the Stack
- Laravel backend
- React frontend
- Laravel Sanctum auth
- Stripe for payments
Review Documentation
- Read API Overview
- Understand auth flow
- Note rate limits
- Review off-limits routes
Set Up Safe Testing
- Create test account(s)
- Use placeholder IDs in code
- Confirm test mode status for payments
- Plan for cleanup
Start Building
- Begin with read-only endpoints
- Test auth flow first
- Add mutations carefully
- Monitor rate limit headers
