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

API keys are issued by the Nozzle team. To request one, contact us and let us know:

• The workspace you need access for
• A short description of what you're building (helps us flag any rate limit considerations)

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 was issued for. 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, contact support and we'll rotate it.

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, schedules, and a versionId (which you'll need if you intend to update the keyword set later — see the keyword sources guide for details).

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.