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

# API Keys

> Create and manage authentication tokens for MCP access

## What Are API Keys?

API keys are secure tokens that let your AI assistant authenticate with ULPI.io. Think of them like passwords, but for machines instead of humans.

Each API key:

* Belongs to your tenant (organization)
* Has specific permissions (scopes)
* Can be revoked at any time
* Tracks usage for billing

## Creating an API Key

<Steps>
  <Step title="Open API Keys">
    Navigate to **API Keys** in your ULPI dashboard
  </Step>

  <Step title="Click Create">
    Press **Create API Key** button
  </Step>

  <Step title="Configure">
    Fill in the key details:

    * **Name**: Descriptive name (e.g., "Production Claude Desktop")
    * **Environment**: Test or Live
    * **Type**: Restricted (recommended) or Unrestricted
    * **Scopes**: MCP permissions
  </Step>

  <Step title="Save Key">
    Copy the key immediately - it's only shown once!
  </Step>
</Steps>

<Warning>
  **Important**: Save your API key in a secure location. ULPI never stores the full key after creation.
</Warning>

## Understanding Environments

### Test Environment

* For development and testing
* Free unlimited usage
* Separate from production data

### Live Environment

* For production use
* Counts toward your billing
* Real customer data

<Tip>
  Start with **Test** keys during setup. Switch to **Live** when you're ready to go to production.
</Tip>

## Understanding Scopes

Scopes control what your API key can do. Available scopes:

| Scope            | Description                 | Required For           |
| ---------------- | --------------------------- | ---------------------- |
| `mcp:search`     | Search documentation        | Claude Desktop, VSCode |
| `mcp:get_doc`    | Get full document content   | Expanding documents    |
| `mcp:list_repos` | List available repositories | Repository browsing    |
| `repo:read`      | Read repository metadata    | Advanced integrations  |
| `repo:write`     | Modify repository settings  | Admin operations       |

### Recommended Scopes for MCP

For typical MCP usage (Claude Desktop/VSCode), enable:

* ✅ `mcp:search`
* ✅ `mcp:get_doc`
* ✅ `mcp:list_repos`

You usually don't need `repo:write` for AI assistants.

## Token Types

### Restricted Tokens (Recommended)

* Require explicit scopes
* More secure
* Can be limited to specific actions
* **Use this for production**

### Unrestricted Tokens

* Access to all features
* Easier for development
* Less secure
* **Only use for testing**

## Managing API Keys

### Viewing Keys

In the API Keys dashboard, you'll see:

* Key name and prefix (first 8 characters)
* Environment (test/live)
* Last used timestamp
* Creation date
* Status (active/expired)

### Revoking Keys

If a key is compromised or no longer needed:

1. Go to **API Keys**
2. Find the key to revoke
3. Click **Revoke**
4. Confirm deletion

<Warning>
  Revoking a key is **immediate**. Any applications using it will lose access.
</Warning>

### Rotating Keys

Best practice: Rotate keys every 90 days

1. Create a new API key
2. Update your MCP configuration
3. Test the new key
4. Revoke the old key

## Key Expiration

API keys can have expiration dates:

<Steps>
  <Step title="Set Expiration">
    When creating a key, set **Expires At** field
  </Step>

  <Step title="Renewal Reminder">
    ULPI will email you 7 days before expiration
  </Step>

  <Step title="Create New Key">
    Generate a replacement key before expiration
  </Step>
</Steps>

<Tip>
  For production keys, set expiration to 90 days for better security.
</Tip>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never commit keys to Git">
    Store API keys in environment variables or secret managers, never in source code.
  </Accordion>

  <Accordion title="Use restricted tokens">
    Always choose "Restricted" type and minimal required scopes.
  </Accordion>

  <Accordion title="Separate keys per environment">
    Create different keys for development, staging, and production.
  </Accordion>

  <Accordion title="Rotate regularly">
    Update keys every 90 days, even if not compromised.
  </Accordion>

  <Accordion title="Monitor usage">
    Check the "Last Used" timestamp regularly for suspicious activity.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### "Invalid API Token" Error

**Possible causes:**

* Key was revoked
* Key has expired
* Wrong key copied (check for extra spaces)
* Using test key in live environment

**Solution:** Generate a new key and update your configuration.

### Key Not Working After Creation

**Wait 30 seconds** - New keys take a moment to propagate across ULPI's infrastructure.

### Can't See My Key

API keys are **only shown once** during creation. If you lost it, you must:

1. Revoke the old key
2. Create a new key
3. Update your configuration

## API Key Limits

| Plan       | Max Keys  | Rate Limit          |
| ---------- | --------- | ------------------- |
| Free       | 3         | 100 requests/day    |
| Pro        | 10        | 10,000 requests/day |
| Enterprise | Unlimited | Custom              |

<Card title="Need More?" icon="arrow-up">
  Upgrade your plan at [app.ulpi.io/billing](https://app.ulpi.io/billing)
</Card>

## Next Steps

You can now use your API key to configure ULPI with your preferred MCP-compatible IDE (Claude Desktop, VSCode, Cursor, Windsurf, Zed, etc.).