Skip to main content

​
Overview

BeatPass uses Laravel Sanctum for SPA (single-page application) authentication. This is a cookie-based session authentication system designed for first-party frontend applications.
BeatPass does not issue API tokens or support third-party integrations. This API is for the BeatPass web application only.

​
Authentication Model

BeatPass uses stateful SPA authentication:

Cookie Sessions

All auth uses secure, HttpOnly session cookies

CSRF Required

State-changing requests require CSRF tokens

No API Tokens

Personal access tokens are not issued

First-Party Only

Third-party integrations not supported

​
SPA Authentication Flow

The BeatPass frontend authenticates using Sanctum’s SPA authentication:
1

Get CSRF Cookie

Before login, request a CSRF cookie:
GET /sanctum/csrf-cookie
This sets the XSRF-TOKEN cookie.
2

Submit Login

POST credentials with the CSRF token:
POST /login
Content-Type: application/json
X-XSRF-TOKEN: {token-from-cookie}

{
  "email": "[email protected]",
  "password": "your-password"
}
3

Handle 2FA (if enabled)

If 2FA is enabled, you’ll receive a two_factor: true response. Submit the TOTP code:
POST /two-factor-challenge

{ "code": "123456" }
4

Session Established

On success, a session cookie is set. All subsequent requests include this cookie automatically.

​
CSRF Protection

All state-changing requests (POST, PUT, DELETE) require CSRF protection.

​
How CSRF Works

  1. Cookie: Sanctum sets an XSRF-TOKEN cookie (URL-encoded)
  2. Header: Include the decoded token in X-XSRF-TOKEN header
  3. Verification: Laravel verifies the header matches the cookie

​
JavaScript Example

// Read CSRF token from cookie
function getCsrfToken() {
  const cookie = document.cookie
    .split('; ')
    .find(row => row.startsWith('XSRF-TOKEN='));
  return cookie ? decodeURIComponent(cookie.split('=')[1]) : null;
}

// Make authenticated request
async function apiPost(url, data) {
  const response = await fetch(url, {
    method: 'POST',
    credentials: 'include', // Include cookies
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'X-XSRF-TOKEN': getCsrfToken()
    },
    body: JSON.stringify(data)
  });
  return response.json();
}

​
Axios Configuration

// Axios automatically handles XSRF-TOKEN cookies
axios.defaults.withCredentials = true;
axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

​
Stateful Domains

Cookie-based authentication is only available from approved BeatPass domains. Requests from other origins will not receive authenticated sessions.
This is a first-party API. Cross-origin requests from third-party domains are not supported.

​
Optional vs Required Auth

​
Optional Auth Endpoints

Many endpoints work without authentication but return enhanced data when authenticated: 
GET /tracks           # Public track list
GET /tracks/{id}      # Track details (shows purchase status if authed)
GET /artists/{id}     # Artist profile (shows follow status if authed)
GET /search           # Search results

​
Required Auth Endpoints

These endpoints require an authenticated session: 
POST /tracks                           # Upload track
PUT  /tracks/{track}                   # Update track
POST /tracks/{track}/purchase/initiate # Purchase flow
GET  /purchases                        # User purchases
GET  /messaging/conversations          # Messages
POST /beat-requests                    # Create request
GET  /producer-intelligence/dashboard  # Analytics

​
Two-Factor Authentication

When 2FA is enabled, the login flow requires an additional step:

​
Initial Login Response (2FA Required)

{
  "two_factor": true,
  "message": "Two factor authentication required"
}

​
Submit 2FA Code

POST /two-factor-challenge
Content-Type: application/json

{
  "code": "123456"
}
Or use a recovery code: 
{
  "recovery_code": "abcd-efgh-ijkl"
}

​
Session Security

​
Best Practices

All API requests must use HTTPS. Cookies sent over HTTP can be intercepted.
Users can log out other sessions from Account Settings → Active Sessions.
Web sessions expire based on server configuration. Re-authenticate when sessions expire.

​
Logging Out

Users can log out of the current session, or log out all other sessions from the Active sessions panel in Account Settings.

​
Authentication Errors

401 Session missing, invalid, or expired.Solution: Re-authenticate by calling /sanctum/csrf-cookie then /login.
{ "message": "Unauthenticated." }
403 User lacks permission for this resource.Solution: Check that your account has the required role or ownership.
419 CSRF token mismatch or session timeout.Solution: Refresh CSRF token by calling /sanctum/csrf-cookie again.

​
Social Login

BeatPass supports social authentication providers:

Google

Available

Facebook

Available

Twitter

Available
Social logins create a BeatPass account and session automatically. You can link additional providers in Account Settings.

​
Next Steps

API Reference

See available endpoints.

Rate Limits

Understand request limits.
Last modified on December 5, 2025