​
Exchange Token

Exchange a Supabase JWT token for a MentraOS core token.
This endpoint is used by the mobile app after Supabase authentication.

​
Endpoint

POST https://api.mentra.glass/api/auth/exchange-token

​
Request Body

{
  "supabaseToken": "eyJhbGciOiJIUzI1NiIs..."
}

​
Response

Success (200): 
{
  "coreToken": "eyJhbGciOiJIUzI1NiIs..."
}
Error (400/401): 
{
  "error": "No token provided"  // or "Invalid token"
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:19-51
  • Verification: Uses SUPABASE_JWT_SECRET environment variable
  • Token Generation: Signs with AUGMENTOS_AUTH_JWT_SECRET
  • Token Expiry: No explicit expiry set on core token

​
Core Token Structure

The generated coreToken contains:
  • sub: User ID from Supabase
  • email: User’s email address
  • organizations: Array of user’s organizations
  • defaultOrg: User’s default organization

​
Generate Webview Token

Generate a temporary token for webview authentication within apps.

​
Endpoint

POST https://api.mentra.glass/api/auth/generate-webview-token

​
Headers

Authorization: Bearer <coreToken>

​
Request Body

{
  "packageName": "com.example.app"
}

​
Response

{
  "success": true,
  "token": "temp_token_abc123..."
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:54-69
  • Middleware: validateCoreToken - Validates the core JWT token
  • Service: Uses tokenService.generateTemporaryToken()

​
Exchange User Token

Exchange a temporary token for user details (called by app backends).

​
Endpoint

POST https://api.mentra.glass/api/auth/exchange-user-token

​
Headers

Authorization: Bearer <appApiKey>
The validateAppApiKey middleware extracts the API key from the Authorization header.

​
Request Body

{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "com.example.app"
}

​
Response

Success: 
{
  "success": true,
  "userId": "user@example.com"
}
Error: 
{
  "success": false,
  "error": "Invalid or expired token"
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:72-93
  • Middleware: validateAppApiKey - Validates app API key
  • Service: Uses tokenService.exchangeTemporaryToken()

​
Exchange Store Token

Special endpoint for the MentraOS Store webview to get full tokens.

​
Endpoint

POST https://api.mentra.glass/api/auth/exchange-store-token

​
Request Body

{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "org.augmentos.store"
}

​
Response

{
  "success": true,
  "userId": "user@example.com",
  "tokens": {
    "supabaseToken": "eyJhbGciOiJIUzI1NiIs...",
    "coreToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:96-145
  • Validation: Only accepts packageName: "org.augmentos.store"
  • Returns: Both Supabase and core tokens for full authentication

​
Hash with API Key

Create a hash using an app’s API key (for secure client-side verification).

​
Endpoint

POST https://api.mentra.glass/api/auth/hash-with-api-key

​
Headers

Authorization: Bearer <coreToken>

​
Request Body

{
  "stringToHash": "data_to_hash",
  "packageName": "com.example.app"
}

​
Response

{
  "success": true,
  "hash": "sha256_hash_result..."
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:148-162
  • Service: Uses appService.hashWithApiKey()
  • Purpose: Allows apps to verify data integrity

​
Generate Signed User Token

Generate a signed JWT token for webview authentication in apps.

​
Endpoint

POST https://api.mentra.glass/api/auth/generate-webview-signed-user-token

​
Headers

Authorization: Bearer <coreToken>

​
Request Body

{
  "packageName": "com.example.app"
}

​
Response

{
  "success": true,
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": "10m"
}

​
Implementation

  • File: packages/cloud/src/routes/auth.routes.ts:176-199
  • Service: Uses tokenService.issueUserToken()
  • Signing: Uses RSA private key for client-side verification
  • Expiration: 10 minutes

​
Error Codes

CodeDescription
400Missing required parameters
401Invalid or expired token
403Forbidden (wrong package name)
500Internal server error

​
Security Notes

  1. All tokens should be transmitted over HTTPS
  2. Core tokens expire after a configured duration
  3. Temporary tokens are single-use and expire quickly
  4. API keys must be kept secret and never exposed client-side