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

# Authentication

> Learn how to authenticate with Graine AI platform

## Overview

Graine AI uses secure authentication to protect your account and data. We support multiple authentication methods for different use cases.

## Web Platform Authentication

### Sign Up

1. Visit [https://graine.ai](https://graine.ai)
2. Click "Sign Up"
3. Choose your sign-up method:
   * **Email/Password**
   * **Google OAuth**
   * **GitHub OAuth** (coming soon)

### Email/Password Sign Up

```plaintext theme={null}
1. Enter your email address
2. Create a strong password (min. 8 characters)
3. Verify your email address
4. Complete organization setup
```

<Note>
  You'll receive a verification email. Click the link to activate your account.
</Note>

### Login

1. Visit [https://graine.ai](https://graine.ai)
2. Click "Log In"
3. Enter your credentials
4. Click "Sign In"

### Password Reset

If you forget your password:

1. Click "Forgot Password" on the login page
2. Enter your email address
3. Check your email for reset link
4. Create a new password

***

## API Authentication

### Getting Your API Token

<Steps>
  <Step title="Log In to Platform">
    Access your Graine AI dashboard
  </Step>

  <Step title="Navigate to Settings">
    Click on your profile → Settings → API Keys
  </Step>

  <Step title="Generate Token">
    Click "Generate New API Key"

    <Warning>
      Copy your API key immediately. You won't be able to see it again!
    </Warning>
  </Step>

  <Step title="Store Securely">
    Save your API key in a secure location (password manager, environment variables)
  </Step>
</Steps>

### Using Your API Token

Include your API token in the Authorization header:

```bash theme={null}
curl https://api.graine.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

```javascript theme={null}
// JavaScript/Node.js
const response = await fetch("https://api.graine.ai/api/v1/agents", {
  headers: {
    Authorization: `Bearer ${YOUR_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});
```

```python theme={null}
# Python
import requests

headers = {
    'Authorization': f'Bearer {YOUR_API_TOKEN}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.graine.ai/api/v1/agents', headers=headers)
```

***

## Session Management

### Session Duration

* **Web Sessions**: 7 days (with auto-refresh)
* **API Tokens**: No expiration (can be revoked manually)

### Security Features

<CardGroup cols={2}>
  <Card title="Automatic Logout" icon="clock">
    Sessions expire after 7 days of inactivity
  </Card>

  <Card title="Secure Cookies" icon="cookie">
    HttpOnly cookies prevent XSS attacks
  </Card>

  <Card title="HTTPS Only" icon="lock">
    All traffic encrypted with TLS 1.3
  </Card>

  <Card title="Token Rotation" icon="arrows-rotate">
    Rotate API keys regularly for security
  </Card>
</CardGroup>

***

## Organization Access

### Understanding Organizations

* Each user belongs to one organization
* Organization ID is automatically assigned
* All resources (agents, campaigns, etc.) are scoped to your organization

### Getting Your Organization ID

Your organization ID is displayed in:

* Dashboard header
* Settings page
* API responses

```javascript theme={null}
// Example API response
{
  "user": {
    "email": "user@example.com",
    "organization_id": "org_abc123xyz",
    "role": "admin"
  }
}
```

***

## Best Practices

### API Key Security

<AccordionGroup>
  <Accordion title="Never commit API keys to version control">
    ❌ **Don't do this:**

    ```javascript theme={null}
    const API_KEY = "sk_live_abc123..."; // Exposed in code
    ```

    ✅ **Do this:**

    ```javascript theme={null}
    const API_KEY = process.env.GRAINE_API_KEY;
    ```
  </Accordion>

  <Accordion title="Use environment variables">
    Store keys in `.env` files: `bash GRAINE_API_KEY=your_key_here
          GRAINE_ORG_ID=your_org_id `
  </Accordion>

  <Accordion title="Rotate keys regularly">
    * Rotate API keys every 90 days - Immediately rotate if compromised - Delete
      unused keys
  </Accordion>

  <Accordion title="Use separate keys for different environments">
    * Development: `sk_dev_...`
    * Staging: `sk_staging_...`
    * Production: `sk_live_...`
  </Accordion>
</AccordionGroup>

### Password Requirements

* Minimum 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one number
* Special characters recommended

<Tip>Use a password manager to generate and store strong passwords.</Tip>

***

## Rate Limiting

API requests are rate-limited to ensure fair usage:

| Limit Type          | Value     |
| ------------------- | --------- |
| Requests per minute | 1,000     |
| Requests per hour   | 50,000    |
| Requests per day    | 1,000,000 |

### Rate Limit Headers

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000
```

### Handling Rate Limits

```javascript theme={null}
async function makeRequest() {
  try {
    const response = await fetch("https://api.graine.ai/api/v1/agents", {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    if (response.status === 429) {
      // Rate limited - wait and retry
      const retryAfter = response.headers.get("Retry-After");
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      return makeRequest(); // Retry
    }

    return response.json();
  } catch (error) {
    console.error("Request failed:", error);
  }
}
```

***

## Troubleshooting

### Common Auth Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Causes:**

    * Invalid API token
    * Expired session
    * Missing Authorization header

    **Solution:**

    * Verify your API token is correct
    * Log in again
    * Check header format: `Bearer YOUR_TOKEN`
  </Accordion>

  <Accordion title="403 Forbidden">
    **Causes:** - Insufficient permissions - Organization mismatch - Resource
    belongs to another org **Solution:** - Contact your admin for permissions -
    Verify your organization ID
  </Accordion>

  <Accordion title="Email verification not received">
    **Solution:**

    * Check spam folder
    * Wait 5 minutes and try again
    * Click "Resend verification email"
    * Contact support if still not received
  </Accordion>
</AccordionGroup>

***

## Security Compliance

### Data Protection

* **Encryption in Transit**: TLS 1.3
* **Encryption at Rest**: AES-256
* **Password Hashing**: bcrypt with salt
* **Session Security**: HttpOnly + Secure + SameSite cookies

### Compliance

<CardGroup cols={3}>
  <Card title="SOC 2 Type II" icon="shield-check">
    Certified for security controls
  </Card>

  <Card title="GDPR" icon="scale-balanced">
    European data protection compliant
  </Card>

  <Card title="HIPAA Ready" icon="user-shield">
    Healthcare compliance available
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore API endpoints
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Create your first agent
  </Card>
</CardGroup>

<Card title="Need Help?" icon="headset" href="/resources/support">
  Contact our support team for authentication issues
</Card>