Skip to main content
The Astral API uses JWT Bearer tokens for user authentication and API keys for organization-level integrations. Every protected endpoint checks for a valid credential on each request — there are no session cookies.

​
Bearer token authentication

Include your access token in the Authorization header on every request to a protected endpoint: 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
A missing or malformed header returns 401 Unauthorized: 
{
  "error": "No authentication token provided"
}

​
Obtaining an access token

There are two ways to get an access token depending on your signup flow.

​
Email-verified signup (two-step)

Use this flow when registering a new user by email:
  1. POST /api/v1/auth/request-verification — send a verification email
  2. POST /api/v1/auth/verify-token — confirm the token is valid and prefill the form
  3. POST /api/v1/auth/complete-signup — create the account and receive an access token
The complete-signup response includes the access_token you use for subsequent requests.

​
Firebase-based signup

If you authenticate users through Firebase (e.g. Google Sign-In, Apple Sign-In), exchange the Firebase ID token for an Astral access token: 
curl -X POST https://app.nexrex.ai/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "firebase_id_token": "<firebase_id_token>",
    "profile_data": {
      "membership_role": "athlete"
    }
  }'
The response includes an access_token and expires_at timestamp.

​
Token expiration and refresh

Access tokens expire. Check the expires_at field in the auth response and refresh before expiry: 
curl -X POST https://app.nexrex.ai/api/v1/auth/token/refresh \
  -H "Authorization: Bearer <current_access_token>"
Response: 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": "2026-04-24T10:00:00Z"
}

​
API key authentication for organizations

Organization integrations (e.g. importing data, managing members in bulk) can authenticate with an API key instead of a user token. Pass the key in the X-API-Key header: 
X-API-Key: nxr_live_abc123...
API keys are scoped to an organization and must be created by a head coach through the organization settings. A missing or invalid key returns 401 Unauthorized: 
{
  "error": "No API key provided"
}
API keys are only shown once at creation time. Store them securely — they cannot be retrieved after that point.

​
Making an authenticated request

Here is a complete example that fetches the current user’s profile after sign-in: 
curl -X GET https://app.nexrex.ai/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "user_id": "uid_abc123",
  "email": "runner@example.com",
  "roles": ["user"],
  "is_verified": true,
  "is_active": true,
  "last_login": "2026-04-23T08:30:00Z"
}

​
Common authentication errors

StatusErrorCause
401No authentication token providedAuthorization header is absent
401No API key providedX-API-Key header is absent
401Invalid API keyThe API key does not match any active key
401token validation errorToken is expired, malformed, or revoked
403Insufficient permissionsToken is valid but the user lacks the required role