Create an API key

Nona read access is driven by API keys.

An API key is bound to one project and can also be limited by:

• environment
• scope

That means an API key is not just a password. It also expresses what kind of config the app should be allowed to read.

Pick the smallest scope that works

• use client for frontend and mobile apps
• use server for backend-only reads
• use all only when both are required

In practice:

• a React Native app usually starts with a client key
• a backend worker usually starts with a server key
• all is best reserved for cases where both sides genuinely need the same values

Environment scoping

If possible, scope the key to the environment it actually needs.

For example:

• mobile production app -> production
• staging web app -> staging
• backend service in production -> production

This reduces accidental cross-environment reads and keeps access narrower.

Recommended first key

For a simple first test, create a project-scoped key, limit it to production if that is your target environment, and match the key scope to the config entry scope.

In admin

1. open Projects
2. open the target project
3. find the API Keys section near the top of the project page
4. enter a key name
5. choose the scope
6. optionally choose an environment such as production
7. click Create
8. copy the generated key value before you leave the page

The key appears in a one-time panel with a copy button. After you dismiss that panel, the secret cannot be recovered. The key list shows a masked fingerprint instead of the secret.

The same section lets you delete an existing key after confirmation. To replace a credential without interrupting consumers, create another key, migrate and verify its consumers, then delete the old key.

With the CLI

Create a scoped key:

nona keys create \
  --project storefront \
  --name "Web app" \
  --scope client \
  --environment production

List keys for the same project:

nona keys list --project storefront

nona keys show --project storefront also works.

Create a replacement when a secret needs to be changed:

nona keys create \
  --project storefront \
  --name "Web app replacement" \
  --scope client \
  --environment production

After updating and verifying consumers, delete the old key:

nona keys delete --project storefront --id 42

Create prints the secret once with a warning. List output contains only metadata and the fingerprint.

A simple decision guide

App type	Suggested first scope
Web frontend	client
Mobile app	client
Backend API	server
Shared backend + frontend read path	all

Security habits

• store API keys in your secrets system or environment variables
• do not hardcode them in source code
• do not give frontend apps a broader scope than they need
• replace keys when your access model changes or a secret may have been exposed
• copy each new key immediately; it cannot be retrieved later
• create, migrate to, and verify a replacement before deleting the old key when uninterrupted access matters
• prefer creating a new narrowly scoped key over reusing one broad key everywhere

Validate the key

After creating a key, test one real read:

curl "https://nona.example.com/api/environments/production/parameters/Features%3ACheckout" \
  -H "X-Api-Key: <your-api-key>"

If the read fails, check the three most common causes first:

• wrong project
• wrong environment
• wrong scope for the entry you are trying to read

API key FAQ

Should I create one broad key for everything?

No.

It is better to create a narrowly scoped key for each real application read surface than to reuse one broad key everywhere.

Should frontend apps use all scope?

Usually no.

Frontend and mobile apps should usually start with client unless there is a real reason they need broader access.

Do I need a separate key per environment?

Often yes.

Environment scoping is a useful way to avoid accidental cross-environment reads and to keep access narrower.

What should I do if a key works in admin but not in the app?

Check the project, environment, and scope alignment first.

Those are the most common reasons a read fails after the key is created.

Next: Fetch your first config value