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

# Authentication

> Authenticate with the Structify API

## Overview

The Structify API uses API keys for authentication. You must include your API key in the `Authorization` header of every request.

## Obtaining an API Key

1. Sign in to [Structify Dashboard](https://app.structify.ai)
2. Navigate to **Settings → API Keys**
3. Click **Create New Key**
4. Give your key a descriptive name
5. Copy the key immediately - it won't be shown again

## Using Your API Key

Include the API key in the `Authorization` header as a Bearer token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    https://api.structify.ai/server/version
  ```

  ```python Python theme={null}
  from structify import Structify

  # Automatically uses STRUCTIFY_API_TOKEN env var
  client = Structify()

  # Or provide explicitly
  client = Structify(api_key="YOUR_API_KEY")

  # Make authenticated requests
  version = client.server.version()
  ```

  ```typescript TypeScript theme={null}
  import { Structify } from '@structify/prospero';

  // Uses STRUCTIFY_API_TOKEN env var by default
  const client = new Structify();

  // Or provide explicitly
  const client = new Structify({
    apiKey: 'YOUR_API_KEY'
  });

  // Make authenticated requests
  const version = await client.server.version();
  ```

  ```javascript JavaScript theme={null}
  const { Structify } = require('@structify/prospero');

  // Uses STRUCTIFY_API_TOKEN env var by default
  const client = new Structify();

  // Or provide explicitly
  const client = new Structify({
    apiKey: 'YOUR_API_KEY'
  });

  // Make authenticated requests
  client.server.version().then(version => {
    console.log(version);
  });
  ```
</CodeGroup>

## Environment Variables

We recommend using environment variables to manage API keys:

<Tabs>
  <Tab title="Linux/macOS">
    ```bash theme={null}
    export STRUCTIFY_API_TOKEN="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    $env:STRUCTIFY_API_TOKEN = "your_api_key_here"
    ```
  </Tab>

  <Tab title=".env file">
    ```bash theme={null}
    # .env
    STRUCTIFY_API_TOKEN=your_api_key_here
    ```

    Then load with `python-dotenv` or similar:

    ```python theme={null}
    from dotenv import load_dotenv
    load_dotenv()
    ```
  </Tab>
</Tabs>

## Security Best Practices

<Warning>
  Never commit API keys to version control. Add them to `.gitignore`:

  ```
  .env
  .env.local
  *.key
  ```
</Warning>

### Key Rotation

Regularly rotate your API keys:

1. Create a new API key
2. Update your applications to use the new key
3. Verify everything works
4. Delete the old key

### Key Scopes

Create separate keys for different environments:

* `dev-key` - Local development
* `staging-key` - Staging environment
* `prod-key` - Production only

### IP Restrictions

For production keys, consider adding IP restrictions:

```python theme={null}
client.user.update(
    api_key_restrictions={
        "allowed_ips": ["192.168.1.1", "10.0.0.0/24"]
    }
)
```

## Rate Limits

API keys have the following rate limits:

| Plan       | Requests/min | Burst  |
| ---------- | ------------ | ------ |
| Free       | 60           | 100    |
| Pro        | 600          | 1000   |
| Enterprise | Custom       | Custom |

When you exceed rate limits, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}
```

## JWT to API Token Exchange

For web applications using Supabase authentication, you can exchange a JWT for an API token:

<CodeGroup>
  ```python Python theme={null}
  # Exchange JWT for API token
  response = client.user.jwt_to_api_token(jwt="your_jwt_token")
  api_token = response.token

  # Use the API token for subsequent requests
  client = Structify(api_key=api_token)
  ```

  ```typescript TypeScript theme={null}
  // Exchange JWT for API token
  const response = await client.user.jwtToApiToken({
    jwt: 'your_jwt_token'
  });
  const apiToken = response.token;

  // Use the API token for subsequent requests
  const client = new Structify({ apiKey: apiToken });
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Your API key is invalid or missing. Check that:

    * The key is correctly formatted
    * You're using `Bearer` prefix
    * The key hasn't expired or been deleted
  </Accordion>

  <Accordion title="403 Forbidden">
    Your API key doesn't have permission for this operation. Check:

    * Key scopes and permissions
    * Team membership for team resources
    * Project access for project resources
  </Accordion>

  <Accordion title="Environment variable not working">
    Ensure the variable is exported:

    ```bash theme={null}
    echo $STRUCTIFY_API_TOKEN
    ```

    In Python, verify it's loaded:

    ```python theme={null}
    import os
    print(os.environ.get("STRUCTIFY_API_TOKEN"))
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Make Your First API Call" icon="rocket" href="/api-reference/endpoints/overview">
    Explore available endpoints
  </Card>

  <Card title="Python SDK Reference" icon="python" href="/sdks/python/reference">
    Detailed Python SDK documentation
  </Card>

  <Card title="TypeScript SDK Reference" icon="js" href="/sdks/typescript/reference">
    Complete TypeScript SDK guide
  </Card>

  <Card title="Rate Limits & Quotas" icon="gauge" href="/api-reference/rate-limits">
    Understanding rate limits
  </Card>
</CardGroup>