API Keys

API keys are the credentials your external system uses to authenticate with Narrative Intelligence. Every request your system makes must carry a valid key. Only programme admins can create and manage keys.

Go to API Keys in the sidebar of the incubator portal to manage your keys.

The keys list is split into Live and Test tabs. Each row shows the key name, its permissions, which cohort it’s restricted to, when it was last used, and its status. Click any row to open the full detail view, where you can also revoke the key.

📸 Screenshot

Image needed: The API Keys page showing the Live/Test tabs, the keys table, and a key detail modal. Save to src/assets/user-guide/api-keys-list.png.

---

Creating a key

Click New Key. A three-step wizard opens — complete each step and click Next to continue.

Step 1 — Key details

Key name — a label for your own reference, for example “Production CRM,” “Partner portal,” or “Test integration.” This name is only visible inside the platform; it’s not sent with API requests.

Environment — choose Live or Test.

Environment	Behaviour
Live	Submissions count as real applications. They appear in your analytics, scores, and reports. Your team can approve or reject them.
Test	Submissions are marked as previews and excluded from analytics and the approval pipeline. Test keys also unlock sandbox endpoints for building without any pipeline or token usage.

You can tell which environment a key belongs to by its prefix: inc_live_ for live keys, inc_test_ for test keys.

See Test Mode & Sandbox for a full explanation of how test submissions and the sandbox work.

Step 2 — Permissions

Select only the permissions your integration actually needs. Giving a key fewer permissions than it needs will cause 403 errors; giving it more than it needs is an unnecessary security risk.

Scope	What it allows
applications:write	Submit applications to a cohort
applications:read	Read the status and detail of submitted applications
insights:read	Read scores and full reports for submitted applications
programs:read	List open cohorts and retrieve programme information
schema:manage	Register a new custom field schema
schema:read	Read the definition of an existing schema

Most integrations need at minimum applications:write and programs:read. If you’re building a two-way sync that reads results back, add applications:read and insights:read.

Step 3 — Restrictions

Cohort restriction — by default, a key can submit to any open cohort in your programme. Select a specific cohort to lock the key to it — for example, for a partner who is only involved in one cohort. A restricted key returns 403 Forbidden if used against a different cohort. Leave blank if your integration works across multiple cohorts or if you’re not sure yet.

Expiry — choose from a preset (30 days, 90 days, 1 year) or leave as Never. After expiry, requests using the key return 401 Expired.

Tip

Setting an expiry is good practice for keys shared with external partners. It limits the blast radius if a key is leaked — it stops working on its own without you needing to remember to revoke it.

After creation

Click Create Key on the final step. The full key value is shown inline on the wizard page immediately after creation.

Caution

Copy the key now. It is never shown again. Store it in a password manager or your system’s secrets manager (for example, as an environment variable, not hardcoded in your source code). If you lose the key, create a new one and revoke the old one.

📸 Screenshot

Image needed: The key creation wizard showing the three steps — Key Details, Permissions, and Restrictions. Save to src/assets/user-guide/api-key-wizard.png.

📸 Screenshot

Image needed: The key reveal step at the end of the wizard, showing the full key with a copy button and the “shown once” warning. Save to src/assets/user-guide/api-key-reveal.png.

---

Using a key in requests

Pass your key as a Bearer token in the Authorization header of every request:

POST /v1/api/applications
Authorization: Bearer inc_live_xxxxxxxxxxxx
Content-Type: application/json

{ ... }

---

Key states

State	What it means
Active	The key is valid and can be used
Expired	The key’s expiry date has passed. Requests return 401.
Revoked	The key has been manually revoked. Requests return 401.

---

Revoking a key

Click the key’s row in the list to open the detail view, then click Revoke key. Confirm when prompted. The key stops working immediately. Revoked keys remain in the list for your records but cannot be reactivated — create a new key if you need to restore access.

Caution

Revoking a key instantly breaks any integration using it. Make sure you have a replacement key ready before revoking a key that’s in active use.

---

Reading key information

The key table shows the most common fields at a glance. Click a row to open the detail view with the full set:

Table columns

• Name — the label you gave when creating it, and the key prefix (e.g. inc_live_ab12cd34…) below it
• Permissions — up to two scope chips, with a count of additional scopes if there are more
• Cohort — which cohort the key is restricted to, or “All” if unrestricted
• Last used — how recently the key made a request
• Status — active or revoked

Detail view (click a row)

• All permissions as chips
• Created date, last used, expiry, cohort restriction, and revoked date if applicable
• Revoke action