Authentication

All Tessellate Renewables API endpoints require authentication via API key.

Quick Start

Include your API key in the X-API-Key header:

curl -X POST https://api.tessellaterenewables.com/solar/optimization/quick \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tess_your_api_key_here" \
  -d '{"site": {"latitude": 35.0, "longitude": -110.0, "capacity_kw": 1000}}'

Getting an API Key

1. Register at tessellaterenewables.com
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy and securely store your key (shown only once!)

Keep Your Key Secret

API keys grant access to your account. Never commit them to version control or expose them in client-side code.

API Key Format

API keys follow the format: tess_xxxxxxxxxxxxx

The tess_ prefix helps identify Tessellate API keys in your codebase.

Using Your API Key

cURLPythonJavaScript

curl -X POST https://api.tessellaterenewables.com/solar/optimization/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tess_your_api_key_here" \
  -d '{
    "site": {
      "latitude": 35.0,
      "longitude": -110.0,
      "capacity_kw": 1000
    },
    "objective": "energy"
  }'

import os
import requests

API_KEY = os.environ.get("TESSELLATE_API_KEY")

response = requests.post(
    "https://api.tessellaterenewables.com/solar/optimization/run",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
    },
    json={
        "site": {
            "latitude": 35.0,
            "longitude": -110.0,
            "capacity_kw": 1000
        },
        "objective": "energy"
    }
)

const API_KEY = process.env.TESSELLATE_API_KEY;

const response = await fetch(
  'https://api.tessellaterenewables.com/solar/optimization/run',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      site: {
        latitude: 35.0,
        longitude: -110.0,
        capacity_kw: 1000
      },
      objective: 'energy'
    })
  }
);

API Key Scopes

API keys can be created with specific scopes to limit access:

Scope	Description
*	Full access (default)
jobs:read	Read optimization job status and results
jobs:write	Submit optimization jobs
reports:read	Download generated reports

Example: Create a key with only read access:

curl -X POST https://api.tessellaterenewables.com/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only dashboard",
    "scopes": ["jobs:read", "reports:read"]
  }'

Rate Limits & Quotas

API access is metered based on your subscription tier:

Tier	Requests/Month	Rate Limit	Price
Free	100	10/min	$0
Starter	5,000	60/min	$99 (one-time)
Pro	50,000	300/min	$499/year
Enterprise	Unlimited	1000/min	$1,499/year

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-Quota-Limit: 5000
X-Quota-Used: 127
X-Quota-Remaining: 4873

Rate Limit Exceeded (429)

If you exceed your rate limit:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 60 requests per minute.",
  "retry_after": 12
}

Wait for retry_after seconds before retrying.

Quota Exceeded (402)

If you exceed your monthly quota:

{
  "error": "quota_exceeded",
  "message": "Monthly quota exceeded. 5000/5000 requests used.",
  "tier": "STARTER",
  "upgrade_url": "/billing/pricing"
}

Upgrade your plan to continue using the API.

Checking Your Usage

Get your current usage and limits:

curl "https://api.tessellaterenewables.com/metering/usage?api_key_id=YOUR_KEY_ID&tier=STARTER"

Response:

{
  "rate_limit": {
    "requests_in_window": 5,
    "limit_per_minute": 60,
    "remaining": 55
  },
  "quota": {
    "requests_this_month": 127,
    "monthly_limit": 5000,
    "remaining": 4873,
    "percent_used": 2.54
  }
}

Error Responses

Status	Error	Description
401	authentication_required	Missing or invalid API key
403	insufficient_scope	API key lacks required scope
429	rate_limit_exceeded	Too many requests per minute
402	quota_exceeded	Monthly quota exceeded

Security Best Practices

1. Never expose keys in client-side code - Use a backend proxy
2. Rotate keys regularly - Regenerate keys periodically
3. Use environment variables - Don't hardcode credentials
4. Use scoped keys - Create keys with minimum required permissions
5. Monitor usage - Watch for unusual activity in your dashboard
6. Revoke compromised keys - Immediately revoke if exposed

Environment Variables

We recommend storing credentials in environment variables:

# .env file (never commit this!)
TESSELLATE_API_KEY=tess_your_api_key_here

import os

api_key = os.environ.get("TESSELLATE_API_KEY")
if not api_key:
    raise ValueError("TESSELLATE_API_KEY environment variable required")

Alternative: Bearer Token

API keys can also be sent as Bearer tokens:

curl -H "Authorization: Bearer tess_your_api_key_here" \
  https://api.tessellaterenewables.com/solar/optimization/quick

This is useful when integrating with tools that only support Bearer authentication.