Skip to content

API keys and webhooks

For connecting Nabu to outside software — like the Nabu command-line tool, or your own scripts and agents that work on a screenplay for you. Most writers never need this page, and that's completely fine.

These two settings live under the Developer group in Settings. They let other software act on Nabu on your behalf — an API key is the password that software uses to sign in, and a webhook is a way for Nabu to ping another service when something happens. If you only ever write inside the Nabu web app, you can safely skip this whole page.

Note: Depending on your plan, this may not be visible yet. During Nabu's private alpha, API Keys and Webhooks appear dimmed in the Settings menu with a small soon label, and you can't open them yet. They'll switch on as Nabu moves past the alpha.

Why you might want an API key

The most common reason is the Nabu command-line tool — a small program called nabu that runs in a terminal. It lets you (or an agent working for you) talk to Nisaba, list your projects, run the wizard, and check on background jobs without opening the web app. The command-line tool lives in its own place and has its own setup guide; this page only covers the one thing it needs from the web app: a key to sign in with.

Note: The Nabu command-line tool is a separate, optional companion to the web app. It's aimed at writers comfortable with a terminal. If that's not you, nothing here is required — your screenplay works fully from the web app alone.

Creating an API key

Here's how to generate a key you can hand to the command-line tool or another piece of software.

  1. Open Settings, then choose API Keys under the Developer group.
  2. Click Create Key.
  3. Give the key a Name you'll recognize later (for example, the name of the computer or tool you'll use it on).
  4. Choose the key's Scopes — what it's allowed to do. The choices are read, write, and admin. For ordinary use with the command-line tool, read and write are enough; leave admin unchecked unless you have a specific reason.
  5. If you'll have an agent do work for you, you can also tick the agent capabilities — these let the key drive Nisaba autonomously (for example, advancing the wizard or writing scenes on its own).
  6. Click to create the key. Nabu shows you the full key once.
  7. Click Copy Key and paste it somewhere safe right away.

Warning: The full key is shown only one time, the moment you create it. Once you dismiss the screen, Nabu can't show it to you again — it only ever stores a scrambled version. If you lose it, you simply make a new one and revoke the old.

A Nabu key always starts with nabu_sk_. That prefix is how the command-line tool recognizes it as a real Nabu key.

The quickest path: let the tool open this page for you

If you have the command-line tool installed, you don't have to find this page by hand. Run nabu login in your terminal and it opens the API Keys page in your browser for you, with the form already filled in — a sensible name, and the read and write scopes pre-ticked (admin is never pre-ticked, on purpose).

When you create the key that way, the page shows an extra Copy CLI command button alongside Copy Key. Click it, paste the copied command into your terminal, and you're connected — no copying the raw key around. Afterward, run nabu doctor in the terminal to confirm everything's wired up.

Tip: nabu login and nabu doctor are commands you type into the command-line tool, not buttons in the web app. The web app's only job here is to mint the key.

Revoking a key

If a key is no longer used, or you think it may have leaked, take it out of service.

  1. On the API Keys page, find the key in your list.
  2. Click Revoke next to it and confirm.

A revoked key stops working immediately. Any tool still using it will simply be turned away, so make a fresh key for anything you still want connected.

What each API-key control does

  • Create Key — Starts a new key. You name it, choose what it can do, and Nabu generates it.
  • Name — A label for you, so you can tell your keys apart. It doesn't affect what the key can do.
  • Scopes (read / write / admin) — How much the key is allowed to do. read can look; write can make changes; admin is powerful and best left off unless you truly need it.
  • Capabilities — Extra permissions for letting an agent act on its own (for example, advancing the wizard or writing scenes). Leave these off if a person is driving.
  • Copy Key — Copies the full key to your clipboard. Available only on the one screen right after creation.
  • Copy CLI command — Appears when you arrived from nabu login. Copies a ready-to-paste terminal command that stores the key for you.
  • Revoke — Permanently disables a key. There's no undo; you just make a new one.

Webhooks

A webhook is a way to have Nabu notify another service when something happens — for example, when a background job finishes or a scene is generated. Instead of you checking back, Nabu reaches out and tells the address you've registered.

This is firmly a developer feature. If you don't run a service that's waiting to hear from Nabu, you can ignore it entirely.

To set one up, open Webhooks under the Developer group and click to create one. You give it a Name, the URL Nabu should call, and tick the event types you care about (the kinds of things you want to be told about). Once it's saved, Nabu starts sending notifications to that address, and you can come back to:

  • Turn a webhook on or off, or edit its details.
  • Delete a webhook you no longer want.
  • View its recent deliveries to see what Nabu has sent and whether each call went through.

When you create a webhook, Nabu gives you a one-time signing secret. Your service uses it to confirm that an incoming message genuinely came from Nabu.

Warning: Like an API key, the webhook signing secret is shown only once, at creation. Copy it then — Nabu won't show it again.

Good to know

  • You almost certainly don't need either of these. Writing a screenplay in Nabu never requires an API key or a webhook. These exist for connecting Nabu to other software.
  • Keys and secrets are shown exactly once. Both an API key and a webhook secret appear a single time. Copy them on the spot; if you lose one, revoke it and make another.
  • Keep the smallest scope that works. When in doubt, give a key only read and write, and leave admin and agent capabilities off. It's easy to make a more capable key later if you find you need one.
  • Revoking is your safety net. If anything ever feels off about a key, revoke it. It stops working at once, and your account stays yours.