How do I authenticate with the Nozzle API?

The Nozzle API uses long-lived API keys. Once you have a key, every request sends it in the Authorization header — that's the whole story.

This guide covers how to get a key, how to use it, and the IDs you'll need to reference your workspace and projects in API calls.

Getting an API key

You can create an API key yourself, right in the app. Go to Settings → Users in the left-hand navigation, click Create API Token, give it a name, and copy the key that's generated. It's shown only once, so save it somewhere safe.

For a step-by-step walkthrough, see How do I create an API token?

You'll get back a token that looks something like this:

abc123def456ghi789.jklmnopqrstuvwxyz0123456789-abcdefghijklmnopqrst

Treat it like a password. It grants full access to the workspace it belongs to, so don't commit it to git, paste it into client-side JavaScript, or share it in public Slack channels. If a key is ever exposed, remove its dedicated user from your Users list and create a new one.

Using the API key

Send the key in the Authorization header on every request, prefixed with Token:

curl 'https://api.nozzle.app/teams?workspaceId=123456789012345' \
  -H 'accept: application/json' \
  -H 'authorization: Token <your_api_key>'

That's it. No OAuth flow, no token refresh, no expiration to manage.

A note about Bearer tokens

You may notice that browser requests to api.nozzle.app use Authorization: Bearer <jwt> instead of Authorization: Token <api_key>. Those Bearer tokens are short-lived JWTs the app uses for authenticated browser sessions — they expire roughly every hour and are intended for the web UI, not for automation.

If you've been grabbing a Bearer token from Chrome DevTools to test API calls, that works for one-off testing but will break in production once the token expires. For any integration or automation, use a Token API key instead.

IDs you'll need

Most API endpoints require at least a workspaceId. Many also require a teamId (a project) and some require a keywordSourceId (a keyword set).

Here's how the IDs fit together:

Workspace (your Nozzle account)
└── Team (a project — these used to be called "teams" in the API and the name stuck)
    └── Keyword Source (a keyword set being tracked)

All Nozzle IDs are integers under 15 digits, so they're safe to use as numbers in JavaScript and Excel without losing precision.

Finding your workspaceId

The workspaceId is in the URL of any page in app.nozzle.io. For example:

https://app.nozzle.io/keyword-sources/823965476044669?workspace=myslug&workspaceId=893121228039810
                                                                       ────────────────
                                                                       this is your workspaceId

Finding your teamId (project)

Once you have a workspaceId, list all projects in it:

curl 'https://api.nozzle.app/teams?workspaceId=<your_workspace_id>' \
  -H 'authorization: Token <your_api_key>'

Response:

{
  "success": true,
  "data": [
    {
      "id": 608677144962928,
      "name": "My Project",
      "slug": "my-project",
      "workspaceId": 893121228039810,
      "createdAt": "2025-06-13T16:15:46Z"
    }
  ]
}

The id field is the teamId you'll use elsewhere.

Finding your keywordSourceId

You can find a keyword source's ID in the URL of its page in app.nozzle.io, or by listing them via the API. See the Admin API reference for full details.

A complete example

Putting it all together — fetching a specific keyword set:

curl 'https://api.nozzle.app/keywordSources/<keyword_source_id>?workspaceId=<your_workspace_id>' \
  -H 'accept: application/json' \
  -H 'authorization: Token <your_api_key>'

The response includes the keyword set's metadata, all phrases, locales, devices, and schedules. For details on how the fields are structured and how to update a keyword set, see the keyword sources guide.

Common errors

Best practices

• Use one API key per integration. If you build multiple tools that hit the API, request a separate key for each. Makes it easier to rotate one without breaking the others.
• Store keys in environment variables or a secrets manager. Never hard-code them in source files.
• Log requests, not headers. When debugging, log the URL and request body — but redact the Authorization header so keys don't end up in logs.
• Rotate after team changes. When someone with key access leaves, request a new key and rotate the old one out.

Need help?

If you run into anything that isn't covered here, reach out — we'd rather hear about it than have you stuck.