Authentication - MentraOS Cloud

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

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

POST http://localhost:8002/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

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

POST http://localhost:8002/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

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

POST http://localhost:8002/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

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

POST http://localhost:8002/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

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

POST http://localhost:8002/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

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

POST http://localhost:8002/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

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

Security Notes

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

​Exchange Token

​Endpoint

​Request Body

​Response

​Implementation

​Core Token Structure

​Generate Webview Token

​Endpoint

​Headers

​Request Body

​Response

​Implementation

​Exchange User Token

​Endpoint

​Headers

​Request Body

​Response

​Implementation

​Exchange Store Token

​Endpoint

​Request Body

​Response

​Implementation

​Hash with API Key

​Endpoint

​Headers

​Request Body

​Response

​Implementation

​Generate Signed User Token

​Endpoint

​Headers

​Request Body

​Response

​Implementation

​Error Codes

​Security Notes

Exchange Token

Endpoint

Request Body

Response

Implementation

Core Token Structure

Generate Webview Token

Endpoint

Headers

Request Body

Response

Implementation

Exchange User Token

Endpoint

Headers

Request Body

Response

Implementation

Exchange Store Token

Endpoint

Request Body

Response

Implementation

Hash with API Key

Endpoint

Headers

Request Body

Response

Implementation

Generate Signed User Token

Endpoint

Headers

Request Body

Response

Implementation

Error Codes

Security Notes