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
2. Click “Sign Up”
3. Choose your sign-up method:
   • Email/Password
   • Google OAuth
   • GitHub OAuth (coming soon)

Email/Password Sign Up

1. Enter your email address
2. Create a strong password (min. 8 characters)
3. Verify your email address
4. Complete organization setup

You’ll receive a verification email. Click the link to activate your account.

Login

1. Visit 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

1. Log In to Platform

   Access your Graine AI dashboard

2. Navigate to Settings

   Click on your profile → Settings → API Keys

3. Generate Token

   Click “Generate New API Key”

   Copy your API key immediately. You won’t be able to see it again!

4. Store Securely

   Save your API key in a secure location (password manager, environment variables)

Using Your API Token

Include your API token in the Authorization header:

curl https://api.graine.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

// 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
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

Automatic Logout

Sessions expire after 7 days of inactivity

Secure Cookies

HttpOnly cookies prevent XSS attacks

HTTPS Only

All traffic encrypted with TLS 1.3

Token Rotation

Rotate API keys regularly for security

---

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

// Example API response
{
  "user": {
    "email": "[e-mail]",
    "organization_id": "org_abc123xyz",
    "role": "admin"
  }
}

---

Best Practices

API Key Security

Never commit API keys to version control

❌ Don’t do this:

const API_KEY = "sk_live_abc123..."; // Exposed in code

✅ Do this:

const API_KEY = process.env.GRAINE_API_KEY;

Use environment variables

Store keys in .env files: bash GRAINE_API_KEY=your_key_here GRAINE_ORG_ID=your_org_id

Rotate keys regularly

• Rotate API keys every 90 days - Immediately rotate if compromised - Delete unused keys

Use separate keys for different environments

• Development: sk_dev_...
• Staging: sk_staging_...
• Production: sk_live_...

Password Requirements

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

Use a password manager to generate and store strong passwords.

---

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/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000

Handling Rate Limits

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

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

403 Forbidden

Causes: - Insufficient permissions - Organization mismatch - Resource belongs to another org Solution: - Contact your admin for permissions - Verify your organization ID

Email verification not received

Solution:

• Check spam folder
• Wait 5 minutes and try again
• Click “Resend verification email”
• Contact support if still not received

---

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

SOC 2 Type II

Certified for security controls

GDPR

European data protection compliant

HIPAA Ready

Healthcare compliance available

---

Next Steps

API Reference

Explore API endpoints

Quickstart Guide

Create your first agent

Need Help?

Contact our support team for authentication issues