# Authentication

NeuraAI uses API keys to authenticate requests. All API requests must include a valid API key in the authorization header.

## Getting Your API Key

1. Sign up for a NeuraAI account at [neura-ai.app](https://neura-ai.app)
2. Navigate to your dashboard
3. Go to the API Keys section
4. Click "Create New API Key"
5. Copy and securely store your API key

<Warning>
  **Keep your API key secure!** Never share it publicly or commit it to version control. Treat it like a password.
</Warning>

## Authentication Method

NeuraAI uses Bearer token authentication. Include your API key in the `Authorization` header of every request:

```
Authorization: Bearer YOUR_API_KEY
```

## Using Authentication

### Python (OpenAI SDK)

The recommended way to authenticate is using environment variables:

```python
import os
from openai import OpenAI

# Set your API key as an environment variable
# export NEURA_API_KEY='your-api-key-here'

client = OpenAI(
    base_url="https://api.neura-ai.app/v1",
    api_key=os.environ.get("NEURA_API_KEY")
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

Alternatively, you can pass the API key directly:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.neura-ai.app/v1",
    api_key="your-api-key-here"  # Not recommended for production
)
```

### cURL

```bash
curl https://api.neura-ai.app/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### JavaScript/Node.js

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.neura-ai.app/v1',
  apiKey: process.env.NEURA_API_KEY
});

const response = await client.chat.completions.create({
  model: 'gpt-5',
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

### Python (Requests)

If you prefer using the requests library directly:

```python
import requests
import os

headers = {
    "Authorization": f"Bearer {os.environ.get('NEURA_API_KEY')}",
    "Content-Type": "application/json"
}

data = {
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello!"}]
}

response = requests.post(
    "https://api.neura-ai.app/v1/chat/completions",
    headers=headers,
    json=data
)

print(response.json())
```

## Setting Environment Variables

### Linux/macOS

Add to your `.bashrc`, `.zshrc`, or `.bash_profile`:

```bash
export NEURA_API_KEY='your-api-key-here'
```

Or set temporarily in your current session:

```bash
export NEURA_API_KEY='your-api-key-here'
```

### Windows (PowerShell)

```powershell
$env:NEURA_API_KEY='your-api-key-here'
```

### Windows (Command Prompt)

```cmd
set NEURA_API_KEY=your-api-key-here
```

### Using .env Files

For local development, use a `.env` file:

```bash
# .env file
NEURA_API_KEY=your-api-key-here
```

Then load it in your application:

```python
from dotenv import load_dotenv
import os
from openai import OpenAI

# Load environment variables from .env file
load_dotenv()

client = OpenAI(
    base_url="https://api.neura-ai.app/v1",
    api_key=os.environ.get("NEURA_API_KEY")
)
```

Install python-dotenv:

```bash
pip install python-dotenv
```

## Managing API Keys

### Creating Multiple Keys

You can create multiple API keys for different applications or environments:

* **Development** - For testing and development
* **Staging** - For pre-production testing
* **Production** - For live applications

This allows you to:

* Rotate keys without downtime
* Track usage per application
* Revoke compromised keys without affecting others

### Rotating Keys

Best practice is to rotate API keys periodically:

1. Create a new API key
2. Update your application to use the new key
3. Test that the new key works
4. Delete the old key

### Revoking Keys

If you suspect a key has been compromised:

1. Go to your dashboard
2. Navigate to API Keys
3. Click "Revoke" on the compromised key
4. Create a new key immediately
5. Update your applications

## Error Responses

### Invalid API Key

```json
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

HTTP Status: `401 Unauthorized`

### Missing API Key

```json
{
  "error": {
    "message": "You didn't provide an API key",
    "type": "invalid_request_error", 
    "code": "missing_api_key"
  }
}
```

HTTP Status: `401 Unauthorized`

### Expired API Key

```json
{
  "error": {
    "message": "This API key has been revoked",
    "type": "invalid_request_error",
    "code": "revoked_api_key"
  }
}
```

HTTP Status: `401 Unauthorized`

## Security Best Practices

### DO:

* ✅ Store API keys in environment variables
* ✅ Use different keys for different environments
* ✅ Rotate keys regularly (every 90 days recommended)
* ✅ Revoke unused or old keys
* ✅ Monitor API usage for unusual activity
* ✅ Use `.gitignore` to exclude `.env` files from version control
* ✅ Limit key permissions when possible

### DON'T:

* ❌ Hardcode API keys in your source code
* ❌ Commit API keys to version control (Git, SVN, etc.)
* ❌ Share API keys via email or messaging apps
* ❌ Use the same key across multiple applications
* ❌ Expose keys in client-side code (JavaScript, mobile apps)
* ❌ Log API keys in application logs
* ❌ Store keys in publicly accessible locations

## Rate Limiting

API keys are subject to rate limits based on your subscription tier. See the [Pricing](/pricing) page for details.

If you exceed your rate limit, you'll receive:

```json
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
```

HTTP Status: `429 Too Many Requests`

## Testing Your Authentication

Quick test to verify your API key works:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.neura-ai.app/v1",
    api_key="your-api-key-here"
)

try:
    models = client.models.list()
    print("✅ Authentication successful!")
    print(f"Available models: {len(models.data)}")
except Exception as e:
    print(f"❌ Authentication failed: {e}")
```

## Need Help?

If you're having authentication issues:

1. Verify your API key is correct (copy-paste to avoid typos)
2. Check that the key hasn't been revoked
3. Ensure you're using the correct base URL: `https://api.neura-ai.app/v1`
4. Verify the Authorization header format: `Bearer YOUR_KEY`
5. Contact support if issues persist