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

# Authentication

> How to authenticate with the usmewe API

# Authentication

The usmewe API uses JWT (JSON Web Tokens) for authentication, powered by Supabase Auth.

## Authentication Flow

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│  User   │────►│ Supabase│────►│ usmewe  │
│         │     │  Auth   │     │   API   │
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     │  1. Login     │               │
     │──────────────►│               │
     │               │               │
     │  2. JWT Token │               │
     │◄──────────────│               │
     │               │               │
     │  3. API Request with JWT      │
     │──────────────────────────────►│
     │               │               │
     │  4. Response  │               │
     │◄──────────────────────────────│
```

## Getting a Token

### Option 1: OAuth (Recommended)

Use Google OAuth for the simplest authentication:

```typescript theme={null}
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

// Sign in with Google
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://yourapp.com/callback'
  }
});
```

### Option 2: Email/Password

```typescript theme={null}
// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'xxx' // Replace with actual password
});

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'xxx' // Replace with actual password
});

// Get JWT
const token = data.session.access_token;
```

## Using the Token

Include the JWT in the `Authorization` header:

```bash theme={null}
curl -X GET "https://api.usmewe.com/v1/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

## Token Refresh

Tokens expire after 1 hour. Refresh before expiration:

```typescript theme={null}
const { data, error } = await supabase.auth.refreshSession();
const newToken = data.session.access_token;
```

## API Key Authentication

For server-to-server integrations, use API keys:

```bash theme={null}
curl -X GET "https://api.usmewe.com/v1/users/me" \
  -H "X-API-Key: your_api_key"
```

<Note>
  API keys are only available for Pro and Enterprise tiers. Contact us to request access.
</Note>

## Error Responses

### Invalid Token

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}
```

### Missing Token

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose tokens in URLs" icon="link-slash">
    Always send tokens in headers, never as query parameters
  </Accordion>

  <Accordion title="Store tokens securely" icon="lock">
    Use secure storage (keychain, encrypted storage) on mobile/desktop
  </Accordion>

  <Accordion title="Implement token refresh" icon="rotate">
    Refresh tokens before they expire to avoid interruptions
  </Accordion>

  <Accordion title="Use HTTPS only" icon="shield">
    All API requests must use HTTPS
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Users API" icon="user" href="/developers/api-reference/users">
    Get user profiles and settings
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/developers/sdks/javascript">
    Use our official SDK
  </Card>
</CardGroup>