Copy Markdown

What you'll accomplish

Create an Org API key with the access it needs, and set up an outbound webhook so an external system finds out about solarOS events as they happen.

Prerequisites

• The Owner or Admin role. API keys require settings.api-keys.manage; webhooks require settings.webhooks.manage. Both are Owner/Admin only by default.

For details on using a key you've created, including headers, base URL, and first call, see Authentication.

Steps

Create an API key

1. Go to Settings → Integrations, open the API Keys tab, and click Create API Key.
2. Give it a Name and pick an Expiration (Never, 30 days, 90 days, or 1 year).
3. Under Access, choose:
   • Limited access (default): starts with no scopes. Add only what this key needs, using the Read / Write / All shortcuts per resource, or select individual scopes. Picking a wildcard scope (resource:*) requires checking a confirmation box.
   • Full access: grants every scope via *:*. Requires checking a confirmation box.
4. Optionally set a Key owner and per-resource API-created record defaults: these apply only when an API request omits an explicit owner.
5. Click Create Key, then Copy the key immediately: it's shown once and can't be retrieved again.

Manage existing keys

The API Keys table shows Name, Access, Owner, Usage, and Status (Active / Revoked / Expired). Each row's menu has:

• Rotate (Active keys only): creates a replacement key and picks an overlap window (1 hour, 24 hours [default], or 7 days) during which both the old and new key work. The new key is shown once, same as at creation.
• Edit: change name, owner, or scopes.
• Revoke: immediately and permanently disables the key. Anything using it stops working right away.

Create a webhook

1. Go to Settings → Integrations, open the Webhooks tab, and click Add webhook.
2. Fill in Name, Endpoint URL (HTTPS required in production), and Events to subscribe to: see Webhook events for the full catalog. Leave Active on to start receiving deliveries immediately.
3. Click Create webhook. A Save your signing secret dialog shows the whsec_... secret once: copy it now.

Verify signatures

Every delivery is a POST with these headers:

• X-SolarOS-Event: the event name.
• X-SolarOS-Delivery: a unique delivery ID.
• X-SolarOS-Timestamp: the signing timestamp.
• X-SolarOS-Signature: v1=<hex>, an HMAC-SHA256 hex digest of ${timestamp}.${rawBody} using your whsec_... secret.

Recompute the HMAC over the timestamp and raw request body with your secret, and compare it to the signature header.

Test and monitor deliveries

From a webhook's row menu, click Test fire to send a synthetic event, then View deliveries to see the result. Each delivery shows a status: Pending, Success, Failed, or Retrying.

Rotate a webhook secret

From the row menu, click Regenerate secret. New deliveries use the new secret immediately; the previous secret stays valid for seven days so you can roll consumers over without downtime.

Verify it worked

• The API key's Usage column shows recent activity once you've made a call with it.
• A webhook's Test fire produces a delivery with status Success in its deliveries drawer.

Common problems

• A webhook delivery shows FAILED. Your endpoint returned a status code other than 2xx, 429, or 5xx. That's treated as permanent; solarOS does not retry it. Fix your endpoint and use Test fire to confirm.
• A delivery is stuck Retrying. Your endpoint returned 429 or a 5xx. solarOS retries with exponential backoff starting at 60 seconds, doubling each time, capped at 60 minutes, up to 8 attempts total before it gives up and marks the delivery FAILED.
• You rotated a webhook secret and deliveries broke. You have seven days from rotation to update your endpoint to the new secret; both secrets verify successfully during that window.
• You revoked an API key by mistake. Revocation can't be undone: create a new key.
• A Limited access key with a wildcard scope won't save. Check the "I understand this key can access all actions for the selected wildcard resources" confirmation box first.