## Overview

The Settings page is your central hub for account configuration. Manage your profile, security settings, API keys, model routing preferences, active sessions, and account deletion - all from one organized interface with six tabs.

## Accessing Settings

Navigate to **Dashboard → Settings** or visit [modelstack.cc/dashboard/settings](https://modelstack.cc/dashboard/settings).

The page has six tabs accessible via URL parameter or tab navigation:

- Profile
- Password
- API Keys
- Model Routing
- Sessions
- Danger Zone

## Profile Tab

Manage your personal information and account details.

### Profile Information

**Name:**

- Update your display name
- Shown in dashboard and emails
- Used in referral tracking (first name only)

**Email:**

- Primary email address for your account
- Used for login and notifications
- Requires verification if changed

**Timezone:**

- Sets your local timezone
- Affects spending cap reset times (5-hour windows, weekly caps)
- Dashboard displays times in your selected timezone

<Info>
  Your timezone setting is critical for time-windowed subscriptions. If you set
  it to US Pacific, your 5-hour windows reset based on Pacific time (e.g., 9am
  PT, 2pm PT, 7pm PT).
</Info>

**Avatar/Profile Picture:**

- Upload custom avatar
- Used in dashboard header
- Supported formats: JPG, PNG, WebP
- Maximum size: 2MB

### Notification Preferences

Control which emails you receive:

| Notification Type   | Description                             | Recommended |
| ------------------- | --------------------------------------- | ----------- |
| **Spending Alerts** | When you reach 80% of window/weekly cap | ✅ On       |
| **Balance Low**     | When prepaid balance falls below $5     | ✅ On       |
| **Security Alerts** | New device login, password change       | ✅ On       |
| **Product Updates** | New models, features, pricing changes   | ⚪ Optional |
| **Marketing**       | Tips, case studies, promotions          | ⚪ Optional |

**Save Changes:**

- Click **Save Profile** button at bottom
- Confirmation message appears
- Changes take effect immediately

## Password Tab

### Change Password

Update your account password for security:

**Requirements:**

- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character

**Process:**

1. Enter **Current Password**
2. Enter **New Password**
3. Confirm **New Password** (must match)
4. Click **Change Password**

**Security Tips:**

- Use a unique password (not reused from other sites)
- Use a password manager (1Password, Bitwarden, etc.)
- Change password every 90 days
- Never share your password

<Warning>
  Changing your password will log you out of all devices except the current one.
  You'll need to sign in again on other devices with the new password.
</Warning>

### Password Reset

If you forgot your password:

1. Sign out of your account
2. Click **Forgot Password** on sign-in page
3. Enter your email address
4. Check email for reset link
5. Follow link to set new password

## API Keys Tab

Manage API keys for authenticating requests to ModelStack.

### Creating API Keys

1. Click **Create API Key** button
2. Enter descriptive name (e.g., "Production Server", "Local Development")
3. Click **Create**
4. Copy the key immediately - it won't be shown again

<Warning>
  API keys are displayed **only once** at creation. Copy and store them
  securely. If you lose a key, delete it and create a new one.
</Warning>

### Key Management

**View Keys:**

- List of all your API keys
- Shows: Name, Key Prefix (first few characters), Created Date, Last Used
- Last Used timestamp helps identify inactive keys

**Revoke Keys:**

- Click **Delete** button next to a key
- Confirm deletion
- Key is immediately invalidated
- Any app using that key will get `401 Unauthorized` errors

### Best Practices

**Naming Convention:**

- Use descriptive names: `Backend-Production`, `Frontend-Staging`, `CI-CD-Pipeline`
- Include environment: production, staging, development
- Include purpose: backend, frontend, testing, automation

**Security:**

- One key per environment (don't reuse across prod/staging/dev)
- Store keys in environment variables, never in code
- Rotate keys every 6 months
- Revoke unused keys immediately
- Use separate keys for CI/CD pipelines

**Usage Tracking:**

- Check "Last Used" column regularly
- Revoke keys not used in 90+ days
- Investigate unexpected usage patterns

## Model Routing Tab

Configure how ModelStack routes requests and which model tiers you want to use.

### Provider Tier Selection

Enable or disable model tiers. Each tier has a separate rate for your bonus wallet and your prepaid wallet — see [Provider Tiers](/docs/models/provider-tiers) for the full breakdown and how a request can split across both wallets.

**Economy Tier:**

- Cheapest models for high-volume, cost-sensitive work (GPT-4o-mini, Claude Haiku, Gemini Flash)
- Prepaid wallet rate: 0.2x by default (80% discount off provider cost)
- Bonus wallet rate: 1.0x (no discount — bonus buys full face value here)
- Payable from bonus wallet or prepaid wallet
- Toggle: **Enabled** or **Disabled** (default: Enabled)

**Standard Tier:**

- Discounted models (GPT-4o-mini, Claude Haiku, Claude Sonnet, Gemini Flash)
- Prepaid wallet rate: 0.5x by default (50% discount off provider cost) — some model families get a deeper discount
- Bonus wallet rate: 1.5x (a 50% markup — bonus balance stretches less far on Standard than its face value)
- Payable from bonus wallet or prepaid wallet
- Toggle: **Enabled** or **Disabled** (default: Enabled)

**Premium Tier:**

- Most capable frontier models (GPT-5.5, Claude Opus)
- Wallet multiplier: 1.00x (full provider price, no discount)
- Payable from prepaid wallet only — bonus balance can never be used for Premium
- Toggle: **Enabled** or **Disabled**

<Info>
  When you disable a tier, models in that tier won't appear as available in your
  dashboard and cannot be used in API requests or stacks.
</Info>

**Use Cases:**

- **Cost control** - Disable Premium to prevent accidental expensive model usage
- **Simplification** - Enable only Standard if you don't need Economy's deeper (but bonus-unfriendly) discount or Premium
- **Team policy** - Enforce tier usage across organization

### Default Model Stack

Set which stack is used by default:

1. Select a stack from dropdown
2. Click **Save**
3. API requests without explicit model parameter will use this stack

**Example:**

```bash
# Without model parameter, uses default stack
curl https://api.modelstack.cc/v1/chat/completions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### Fallback Behavior

Configure what happens when a requested model is unavailable:

| Option                  | Behavior                          | Use When                                     |
| ----------------------- | --------------------------------- | -------------------------------------------- |
| **Fail immediately**    | Return error if model unavailable | You need predictable model usage             |
| **Fallback to similar** | Try similar model from same tier  | You prioritize availability over specificity |
| **Fallback to cheaper** | Try cheaper alternative           | Cost is more important than specific model   |

**Save Changes:**

- Click **Save Routing Preferences** button
- Settings apply immediately to new requests

## Sessions Tab

View and manage active login sessions across all your devices.

### Active Sessions

List of all devices/browsers where you're currently logged in:

**Session Information:**

- **Device** - Browser and operating system (e.g., "Chrome on macOS")
- **Location** - Approximate location based on IP (e.g., "San Francisco, CA")
- **Last Active** - When this session was last used
- **IP Address** - Public IP address of the session
- **Current Session** - Highlighted if it's your current browser

**Revoking Sessions:**

1. Find the session you want to end
2. Click **Revoke** button
3. Confirm revocation
4. User is logged out on that device

<Tip>
  Regularly review active sessions and revoke any you don't recognize. This
  helps protect your account from unauthorized access.
</Tip>

### Session Security

**When to revoke sessions:**

- You see an unfamiliar device or location
- You logged in on a public/shared computer and forgot to sign out
- Your password was potentially compromised
- You want to force re-authentication everywhere

**Revoke All Sessions:**

- Button to sign out everywhere except current device
- Useful after password change or security concern
- Requires sign-in again on all other devices

**Session Expiration:**

- Sessions expire after 30 days of inactivity
- Signing in extends the session by 30 days
- No activity = automatic sign-out for security

## Danger Zone Tab

Destructive actions that cannot be easily reversed.

### Export Account Data

Download all your account data:

**What's Included:**

- Profile information
- API keys (names only, not actual keys)
- Model stacks configuration
- Request history (within retention period)
- Billing history
- Referral data

**Process:**

1. Click **Request Export**
2. Data is prepared (may take a few minutes)
3. Download link sent to your email
4. Link expires after 7 days

**Format:**

- JSON file with all data
- Easy to parse programmatically
- Compliant with data portability regulations

### Delete Account

Permanently delete your ModelStack account.

<Warning>
  Account deletion is **permanent and irreversible**. All data is deleted within
  30 days and cannot be recovered.
</Warning>

**What Gets Deleted:**

- ✅ Profile and account information
- ✅ All API keys (invalidated immediately)
- ✅ Model stacks and configurations
- ✅ Request history and analytics
- ✅ Billing history (after 7 years for compliance)
- ✅ Referral data and codes
- ✅ Active sessions (logged out everywhere)

**What Happens:**

- Subscription cancelled immediately (no refund for partial month)
- Prepaid balance forfeited (non-refundable)
- All API keys stop working instantly
- Your email address can be reused to create a new account after 90 days

**Process:**

1. Click **Delete Account** button
2. Read the warning and consequences
3. Type your password to confirm
4. Type `DELETE` in the confirmation box
5. Click **Permanently Delete Account**
6. Account marked for deletion
7. Deletion completes within 30 days

**Alternatives to Deletion:**

- **Cancel subscription** - Stop paying but keep account
- **Revoke API keys** - Stop API access but keep dashboard access
- **Export data first** - Download your data before deleting

## Keyboard Shortcuts

Navigate settings faster with keyboard shortcuts:

| Shortcut       | Action                   |
| -------------- | ------------------------ |
| `Cmd/Ctrl + 1` | Go to Profile tab        |
| `Cmd/Ctrl + 2` | Go to Password tab       |
| `Cmd/Ctrl + 3` | Go to API Keys tab       |
| `Cmd/Ctrl + 4` | Go to Model Routing tab  |
| `Cmd/Ctrl + 5` | Go to Sessions tab       |
| `Cmd/Ctrl + 6` | Go to Danger Zone tab    |
| `Cmd/Ctrl + S` | Save current tab changes |

## Common Questions

<AccordionGroup>
  <Accordion title="Can I have multiple email addresses?">
    No, each account has one primary email. If you need multiple accounts,
    create separate accounts with different emails.
  </Accordion>
  <Accordion title="What happens if I disable all tiers?">
    You won't be able to make API requests since no models are available. At
    least one tier must be enabled.
  </Accordion>
  <Accordion title="Can I recover deleted API keys?">
    No, deleted keys are permanently invalidated. Create a new key if needed.
  </Accordion>
  <Accordion title="How do I know if someone else is using my account?">
    Check the **Sessions** tab for unfamiliar devices or locations. Enable email
    notifications for security alerts.
  </Accordion>
  <Accordion title="Can I undo account deletion?">
    No, account deletion is permanent. Export your data first if you might want
    it later.
  </Accordion>
  <Accordion title="Why isn't my timezone showing correct reset times?">
    Make sure you've saved your timezone in the Profile tab. It may take up to 1
    hour for changes to fully propagate.
  </Accordion>
</AccordionGroup>

## Related Documentation

- [API Keys](/docs/dashboard/api-keys) - Detailed guide on API key management
- [Billing & Balance](/docs/billing/balance) - How timezone affects cap resets
- [Models](/docs/dashboard/models) - Understanding provider tiers
- [Security Best Practices](/docs/api-reference/authentication) - Protecting your API keys