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

# Projects & API Keys

> Organize integrations and authenticate API requests

## Projects

A **project** represents your integration with Yield.xyz. Projects provide logical separation for different products, environments, or business units — each with its own API keys, fee configurations, and usage analytics.

<CardGroup cols={2}>
  <Card title="Single product" icon="cube">
    One project for your entire application — simplest setup for most integrations.
  </Card>

  <Card title="Multi-tenant" icon="cubes">
    Separate projects per product line or white-label client — useful for platforms serving multiple brands.
  </Card>
</CardGroup>

<Tip>
  Start with a single project. You can always add more later as your integration grows.
</Tip>

***

## API Keys

API keys authenticate your requests to the Yield.xyz API. Each key is scoped to a project and environment.

### Creating API Keys

API keys are created in the [Yield.xyz Dashboard](https://dashboard.yield.xyz). Navigate to **Settings → API Keys** to generate new keys.

<Warning>
  **Copy your API key immediately after creation.** Keys are only displayed once. If lost, generate a new one and revoke the old key.
</Warning>

### Authentication

Include your API key in the `x-api-key` header on every request:

```bash theme={null}
curl https://api.yield.xyz/v1/yields \
  -H "x-api-key: your_api_key_here"
```

***

## Key Permissions

<Tabs>
  <Tab title="Read-Only">
    **For discovery and portfolio tracking**

    * Query yields (`GET /yields`)
    * Fetch balances and positions
    * List networks and providers

    **Cannot:** Create actions, submit transactions

    **Use case:** Public-facing dashboards, yield browsers
  </Tab>

  <Tab title="Read-Write (Default)">
    **For full integrations**

    * All read operations, plus:
    * Create enter/exit/manage actions
    * Submit transaction hashes
    * Track action lifecycle

    **Use case:** Wallet integrations, earn products
  </Tab>
</Tabs>

***

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Server-side only" icon="server">
    Never expose API keys in client-side code. Make all API calls from your backend.
  </Card>

  <Card title="Environment variables" icon="file-code">
    Store keys in environment variables, not source code. Never commit keys to version control.
  </Card>

  <Card title="Rotate regularly" icon="arrows-rotate">
    Generate new keys periodically. Revoke immediately if a key is compromised.
  </Card>

  <Card title="Separate by environment" icon="split">
    Use different keys for production, staging, and development. Never share keys across environments.
  </Card>
</CardGroup>

***

## Error Responses

| Status                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid API key                      |
| `403 Forbidden`         | Valid key but access denied (e.g., geoblocking) |
| `429 Too Many Requests` | Rate limit exceeded — retry after backoff       |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/quickstart">
    Run your first API request
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/documentation/plans-limits/rate-limits">
    Understand rate limiting by plan
  </Card>
</CardGroup>