Authentication

Every call to the Public API carries a workspace secret key. This page covers how to get a key, how to send it, what it can reach and what to do when a call is refused. Read it before you write your first request.

Get a key

Grona issues secret keys for your workspace. There is no page in the Grona dashboard for creating, rotating or revoking keys yourself. To get a key, or to rotate or revoke one, email support@grona.ai.

A key looks like this:

grona_sk_<keyId>_<secret>

Treat the whole string as one opaque value. Do not split it or build it from parts.

Grona stores only a hash of the secret, so nobody at Grona can read your key back to you. If you lose it, ask for a new one.

v1 has no test mode and no separate test keys. A key acts on the real campaigns of its workspace. New campaigns start paused, so you can create, edit and preview a campaign without showing it to visitors until you set it live.

Send the key

Send the key in one of two headers. Both work on every /v1 endpoint that takes a key, so pick one and use it everywhere.

curl

# Authorization header
curl https://api.grona.ai/v1/campaigns \
  -H "Authorization: Bearer $GRONA_SECRET_KEY"

# X-API-Key header
curl https://api.grona.ai/v1/campaigns \
  -H "X-API-Key: $GRONA_SECRET_KEY"

Node

// list.mjs: run with `node list.mjs` (Node 18 or later).
const res = await fetch('https://api.grona.ai/v1/campaigns', {
  headers: { Authorization: `Bearer ${process.env.GRONA_SECRET_KEY}` },
});
const { data, meta } = await res.json();
console.log(`${meta.count} campaigns in workspace ${meta.workspaceId}`);

The workspace comes from the key

Grona resolves the workspace from the key on every call. The workspace is never part of a URL or a request body, and meta.workspaceId in every successful response tells you which workspace answered.

This also means a key can only read and change its own workspace. Ids are looked up inside the key’s workspace, so a campaign or variation id from another workspace returns 404 not_found.

Keep the key on your servers

The secret key can create, change and delete every campaign in your workspace. Anyone who has it can do the same.

• Store it in an environment variable or your secret manager. The samples on these pages read it from GRONA_SECRET_KEY.
• Call the API from your backend only. Never put the key in browser JavaScript, a mobile app, a public repository or a support ticket.
• Keep it out of logs, error reports and analytics. Redact the Authorization and X-API-Key headers if your HTTP client logs requests.
• Give it only to the services that call Grona.

Caution

If a key may have leaked, email support@grona.ai to revoke it straight away, then update every server that used it with the replacement.

Rotate or revoke a key

Rotation and revocation go through Grona support. Email support@grona.ai and say which key you want replaced or revoked. Rotate when someone who had access leaves, when a key may have been exposed, or on your own schedule. After the change, update every server that calls Grona.

When authentication fails

A missing, malformed, unknown or revoked key returns 401 with the usual error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

To fix it, check that:

• the header is spelled Authorization: Bearer <key> or X-API-Key: <key>, with no quotes or extra spaces around the key;
• the full key is present, starting with grona_sk_, and the environment variable is set in the process that makes the call;
• the key has not been rotated or revoked.

Do not retry a 401 in a loop. It will not succeed until the key changes.

Endpoints that do not use your key

Two kinds of URL work without your secret key, by design.

• Editor links. An editUrl such as https://api.grona.ai/v1/editor/launch?token=... is opened in a browser. The short-lived token inside it is what lets the editor open, so treat the link as a secret. See Visual editor links.
• Mobile SDK endpoints. The Android and iOS SDKs fetch their signed config, send events and pair preview devices without a secret key. The app carries only the public workspace key. Your backend still uses the secret key for the mobile grants API.

Next steps

• Errors: every error code and how to fix it.
• Conventions: ids, timestamps and safe retries.