Manage API keys

API keys authorize reads of workspace content through the delivery API. You manage them on the "API keys" tab in workspace settings, which only owners and maintainers can see. An API key does not sign you in to the dashboard.

Issue a key

1. Open the workspace you want to connect to and select the workspace name in the header → "Settings and plan".
2. Open the "API keys" tab and select "New API key".
3. In "Key name", enter a name that shows what the key is for, such as "Production server" or "Local development".
4. Under "Access scope", choose "All APIs (including APIs that will be added in the future)" or "Selected APIs only". If you choose "Selected APIs only", select one or more APIs.
5. Choose a "Validity period" and select "Create".
6. In the "Save API key" dialog, copy the key and store it in a safe place. Then select "Saved".

The full key is shown only once, immediately after creation. You cannot close the dialog with "Saved" until you have copied it. If you lose the key, issue a new one. A key works only in the workspace it was issued in.

View keys

The list shows each key's name, the start of the key (xxxx••••••), its access scope ("All APIs" or "n APIs"), validity period, creation date, and last use.

Open the "⋯" menu on a row to choose "Rename key", "Copy key prefix", or "Delete". Selecting a row also opens the edit screen.

Use a key in your app

If you set up with the CLI, enter the key when init asks for it. If you set up manually, store it in a private environment variable in your runtime environment.

GENKO_API_KEY=paste-your-issued-key-here

const apiKey = process.env.GENKO_API_KEY;if (!apiKey) throw new Error("Set GENKO_API_KEY.");

When you call the API directly, send the key in the X-API-KEY header. Do not put it in the URL as a query parameter.

curl 'https://api.genko.me/v1/your-workspace/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}"

Do not commit .env.local to Git. Set the production key as an environment variable on your hosting provider. Do not give it a public prefix such as NEXT_PUBLIC_, and do not include it in JavaScript sent to the browser. If you expose a key for browser use, treat it as read-only and ensure it can access published content only. Delivery API CORS * is intentional for browser access; it does not hide a key or restrict its origin.

API access scope

A key is tied to the workspace that issued it. You can use it with that workspace's delivery API and with _schema for type generation. It cannot create, update, or delete content.

"All APIs" includes APIs you add later. "Selected APIs only" limits reads to the APIs you selected. Requests for any other API return 404, and that API is left out of _schema. Reference fields that point to an API outside the scope are not expanded and return the original reference ID.

You can change the access scope on the edit screen (row menu → "Rename key"). A change takes effect once it is saved. If you rename an API or change its endpoint, keys keep access to it. If you delete an API and create a new one with the same endpoint, keys do not carry over to it.

Keys normally retrieve published content. To get a draft, you also need the draftKey for that entry. See Draft preview.

Validity period

When you create a key, choose "30 days", "90 days", "1 year", or "No expiry". You can also choose "Custom period" and pick a start and end date on the calendar. The default is 90 days from today. A custom period can end up to 5 years from today, and the start and end date can be the same day.

Dates follow the time zone set on your account. A key works from 0:00 on the start date to 23:59 on the end date.

Requests made before the start date are rejected. If you know the switchover date, you can issue the key in advance and set it in your environment variables. A key with no expiry works until you delete it, so set an end date if the key is only needed for a fixed period.

Extend/change the period

Expired keys stay in the list marked "Expired". To use one again, open the edit screen, choose a new "Validity period", and select "Save". To leave the period as it is, keep "Do not change" selected. The key itself does not change, so you do not need to update your environment variables.

Notification email before deadline

Seven days before a key expires, every owner and maintainer of the workspace receives an email saying the API key is about to expire. The email shows the workspace name, key name, start of the key, and expiry date.

The email has a link to change the validity period. It opens the edit screen for that key. If you are not signed in, you go to the edit screen after you sign in. If the key has already been deleted, a message says so.

No email is sent for a key that expires within 7 days of being created. If you change the validity period, you get another email 7 days before the new expiry date.

Rotate keys

To replace a key that is in use, follow this order.

1. Issue a new key in the same workspace.
2. Update the environment variables for all apps and build environments you use.
3. Restart or redeploy as needed, and confirm that your apps can fetch content.
4. Delete the old key.

If you suspect a key has leaked, delete it first. Apps that use the deleted key get an authentication error, so switch them to a new key.

Troubleshoot connections

The API returns 401 when the key is missing, disabled, or outside its validity period. For validity errors, the message tells you which case it is:

• Before the start date: This API key's validity period has not started yet.
• After the end date: This API key has expired.

403 means the key belongs to a different workspace. 429 means you hit the per-key rate limit, which is 300 requests per minute by default. Requests for _schema need a key as well.

For fixes, see Errors and limits.