Authentication API

Running Days uses Apple Sign-In with JWT tokens for authentication.

Overview

Authentication uses:

Apple Sign-In with PKCE and nonce validation
JWT access tokens (15 minute expiry)
Refresh token rotation with database tracking
httpOnly secure cookies for token storage

Endpoints

Initiate Apple Sign-In

http

GET /api/v1/auth/apple

Redirects to Apple’s authentication page with PKCE challenge.

Query Parameters: | Parameter | Type | Description | |-----------|------|-------------| | redirect_uri | string | Where to redirect after auth |

Apple Callback

http

POST /api/v1/auth/apple/callback

Handles the OAuth callback from Apple.

Request Body:

json

{
  "code": "authorization_code",
  "id_token": "apple_identity_token",
  "state": "csrf_state"
}

Response: Sets httpOnly cookies and redirects to app.

Get Current User

http

GET /api/v1/auth/me

Returns the authenticated user’s information.

Response:

json

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T08:00:00Z"
}

Refresh Token

http

POST /api/v1/auth/refresh

Rotates the refresh token and issues new access token.

Response: Sets new httpOnly cookies.

Logout

http

POST /api/v1/auth/logout

Revokes the current session and clears cookies.

List Sessions

http

GET /api/v1/auth/sessions

Lists all active sessions for the current user.

Response:

json

{
  "sessions": [
    {
      "id": "session_123",
      "userAgent": "Mozilla/5.0...",
      "lastUsed": "2024-01-15T10:00:00Z",
      "current": true
    }
  ]
}

Revoke Session

http

DELETE /api/v1/auth/sessions/:id

Revokes a specific session by ID.

Security Notes

PKCE Required: All Apple Sign-In flows use PKCE with S256 challenge
Nonce Validation: Identity tokens are validated with server-generated nonce
Token Rotation: Refresh tokens are single-use and rotated on each refresh
Cookie Security: All auth cookies are httpOnly, secure, and SameSite=Lax