> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> REST endpoints for authentication and token management

## Exchange Token

Exchange a Supabase JWT token for a MentraOS core token.

<Warning>
  This endpoint is used by the mobile app after Supabase authentication.
</Warning>

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/exchange-token
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/exchange-token
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/exchange-token
  ```
</CodeGroup>

### Request Body

```json theme={null}
{
  "supabaseToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

### Response

Success (200):

```json theme={null}
{
  "coreToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

Error (400/401):

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/generate-webview-token
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/generate-webview-token
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/generate-webview-token
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json theme={null}
{
  "packageName": "com.example.app"
}
```

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/exchange-user-token
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/exchange-user-token
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/exchange-user-token
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <appApiKey>
```

<Note>
  The validateAppApiKey middleware extracts the API key from the Authorization header.
</Note>

### Request Body

```json theme={null}
{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "com.example.app"
}
```

### Response

Success:

```json theme={null}
{
  "success": true,
  "userId": "user@example.com"
}
```

Error:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/exchange-store-token
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/exchange-store-token
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/exchange-store-token
  ```
</CodeGroup>

### Request Body

```json theme={null}
{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "org.augmentos.store"
}
```

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/hash-with-api-key
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/hash-with-api-key
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/hash-with-api-key
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json theme={null}
{
  "stringToHash": "data_to_hash",
  "packageName": "com.example.app"
}
```

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/auth/generate-webview-signed-user-token
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/auth/generate-webview-signed-user-token
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/auth/generate-webview-signed-user-token
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json theme={null}
{
  "packageName": "com.example.app"
}
```

### Response

```json theme={null}
{
  "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

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