Authentication

What you'll accomplish

Create a working Org API key and make a successful first call with it.

Prerequisites

The Owner or Admin role. Creating and managing API keys requires the settings.api-keys.manage permission, which only those two roles hold by default.

Steps

1. Create a key

Go to Settings → Integrations, open the API Keys tab, and click Create API Key. Give it a name (e.g. "Zapier integration" or "Nightly sync script") and pick a scope preset:

Preset	What it grants
`least_privilege`	Nothing beyond `/whoami`: you attach explicit scopes yourself.
`read_only`	Read access (`*:read`-style) across leads, customers, properties, opportunities, quotes, contracts, projects, work orders, service appointments, cases, and more.
`operations`	Full read/write (`resource:*`) across those same resources: the preset most integrations want.
`full_access`	Every scope (`:`). Use sparingly.

Click through to create the key. Copy it immediately: the full key (sk_live_...) is shown exactly once and can't be retrieved again.

2. Send it as a header

Every request needs the key in one of two headers:

Authorization: Bearer sk_live_YOUR_KEY_HERE

or, for clients that can't set Authorization:

x-api-key: sk_live_YOUR_KEY_HERE

3. Make your first call

curl -X GET "https://app.solaros.io/api/v1/whoami" \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE"

const response = await fetch("https://app.solaros.io/api/v1/whoami", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SOLAROS_API_KEY}`,
  },
});
const result = await response.json();
console.log(result);

import os
import requests

response = requests.get(
    "https://app.solaros.io/api/v1/whoami",
    headers={"Authorization": f"Bearer {os.environ['SOLAROS_API_KEY']}"},
)
print(response.json())

Verify it worked

The response's data includes your organization and, nested under data.apiKey, the key's identity and the scopes granted to it:

{
  "data": {
    "organizationId": "org_abc123",
    "organization": { "id": "org_abc123", "name": "Acme Solar" },
    "apiKey": {
      "id": "key_1",
      "name": "Nightly sync script",
      "prefix": "sk_live_abcdef12",
      "scopes": ["leads:*", "customers:*", "properties:*", "..."],
      "scopePreset": "operations",
      "rateLimitPolicy": { "limit": 250, "windowSeconds": 3600 },
      "ipAllowlist": { "enabled": false, "entries": [] },
      "metadata": {},
      "defaultOwners": {},
      "isRotationGrace": false
    }
  },
  "meta": {
    "requestId": "req_...",
    "version": "v1",
    "timestamp": "...",
    "rateLimit": { "limit": 250, "remaining": 249, "reset": 1758456000 }
  }
}

Common problems

You lost the key. There's no way to view a key's plaintext again after creation; only a bcrypt hash and a masked prefix are stored. Revoke it and create a new one, or use Rotate if you need overlap while you update a live integration.
401 on a key that looks right. Check the Status column on the API Keys tab: it's one of Active, Revoked, or Expired. A revoked or expired key returns 401 even if the string itself is correctly formatted.

Was this page helpful?