Skip to main content

​
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:
ComponentImplementation
Session authCookie-based sessions
API tokensNot issued (no bearer tokens)
Third-party integrationsNot supported
CSRF protectionRequired for POST/PUT/DELETE
For web applications:
1

Get CSRF Cookie

GET /sanctum/csrf-cookie
This sets the XSRF-TOKEN cookie.
2

Include CSRF Token

For POST/PUT/DELETE requests, include the token:
X-XSRF-TOKEN: {token from cookie}
3

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": "..."}
4

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.
This means:
ActionImpact
POST/PUT/DELETE requestsReal data is modified
PurchasesReal charges occur
UploadsReal content is published
MessagesReal users receive messages

​
Development Best Practices

PracticeWhy
Use personal test accountsAvoid affecting real users
Test with minimal dataDon’t create spam content
Clean up test dataDelete test uploads promptly
Never test payments with real cardsUse 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.
EnvironmentPayment Behavior
ProductionReal charges
Test mode (if enabled)Stripe test cards accepted

​
Test Card Numbers (Stripe Test Mode Only)

If test mode is available:
Card NumberBehavior
4242 4242 4242 4242Succeeds
4000 0000 0000 0002Declines
4000 0000 0000 9995Insufficient funds
Never use test card numbers on production. They will fail and may flag your account.

​
Using Placeholder IDs

When developing or documenting:
EntityPlaceholder FormatExample
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}
Not: 
GET /api/v1/tracks/12345

​
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.
The API only documents endpoints available to regular authenticated users. If you encounter a 403 Forbidden response, the endpoint requires permissions you don’t have.

​
Safe API Usage

​
Do

  • 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

​
Standard Error Format

{
  "message": "Human-readable error",
  "errors": {
    "field": ["Validation error message"]
  }
}

​
HTTP Status Codes

CodeMeaningAction
200SuccessProcess response
201CreatedResource created
400Bad RequestFix request format
401UnauthorizedRe-authenticate
403ForbiddenCheck permissions
404Not FoundResource doesn’t exist
422Validation ErrorFix input data
429Rate LimitedBack off and retry
500Server ErrorReport to support
See Error Catalog for feature-specific errors.

​
Getting Help

TopicContact
API questions[email protected]
Security concerns[email protected]
Partnership inquiries[email protected]

​
Documentation

TopicLocation
API Overview/developers/overview
API Reference/developers/api-reference/overview
Authentication/developers/auth
Rate Limits/developers/rate-limits
Error Catalog/developers/error-catalog

​
Checklist for New Developers

1

Get Access

  • Obtain development account credentials
  • Set up local environment
  • Understand the session-based auth flow
2

Understand the Stack

  • Laravel backend
  • React frontend
  • Laravel Sanctum auth
  • Stripe for payments
3

Review Documentation

  • Read API Overview
  • Understand auth flow
  • Note rate limits
  • Review off-limits routes
4

Set Up Safe Testing

  • Create test account(s)
  • Use placeholder IDs in code
  • Confirm test mode status for payments
  • Plan for cleanup
5

Start Building

  • Begin with read-only endpoints
  • Test auth flow first
  • Add mutations carefully
  • Monitor rate limit headers

API Overview

Full API introduction.

Error Catalog

Error codes and resolutions.
Last modified on December 5, 2025