DocsAPI Reference
Open API console

Authentication

Every request carries an API key on the X-API-Key header. A key belongs to your workspace, never to an individual person, so it keeps working when someone leaves the team.

Sending a key

cURL
curl -H "X-API-Key: nubo_your_key_here" \
  https://api.nubo-chat.com/v1/usage

Keys look like nubo_ followed by 43 characters. There is no OAuth flow, no token exchange and no expiry handshake — the key is the credential.

Creating a key

Keys are created in the Nubo portal, on the Developer page. Give each one a name describing the system that will use it — “Zapier production”, “nightly warehouse sync” — so that months later you can tell what would break if you revoked it.

You will see the key exactly once

Nubo stores a hash of your key, not the key itself, so it cannot be shown again after the dialog closes. Copy it into your secret store immediately. If you lose it, revoke that key and create another — there is no recovery.

You can choose an expiry when creating a key, or leave it open-ended. A workspace can hold up to 20 active keys at once; expired and revoked keys do not count toward that.

What a key can reach

A key grants read access to every project in the workspace that owns it, not to a single chatbot. There is no per-project or per-endpoint permission model yet, so treat a key as equivalent to read access over the whole workspace.

Server-side only

Never put a key in a browser app, a mobile app, or anything else shipped to end users — a key in client-side code is a key you have published. The API refuses browser origins by default for exactly this reason. Call it from a server, a scheduled job, or an automation platform that stores secrets properly.

Rotating a key

There is no rotate button, and that is deliberate: a “rotate” that keeps the old key alive for a grace period leaves you unsure which callers actually moved. Because a workspace can hold many keys at once, you can rotate with no downtime and no ambiguity:

  • Create a second key alongside the first.
  • Move your callers onto it, one at a time.
  • Watch the Last used column on the old key until it stops advancing.
  • Revoke the old key.

That last-used timestamp is the point of the exercise — it tells you whether anything is still authenticating with the old credential before you break it. It updates within about a minute of a call.

Revoking a key

Revocation is immediate and permanent. Within seconds, every request using that key starts returning 401 with code revoked_api_key. There is no undo and no grace period — to restore access you create a new key and update your callers.

Revoke immediately if a key is pasted into a ticket, committed to a repository, or shared outside the team. Creating a replacement takes seconds; a leaked key with read access to your whole workspace does not expire on its own.

When authentication fails

All authentication failures return 401 with a specific code, so your client can tell a typo from a revocation:

401 response
{
  "error": {
    "code": "revoked_api_key",
    "message": "The provided API key has been revoked.",
    "traceId": "0HN7A2QK9V1M4:00000003"
  }
}

The distinct codes are missing_api_key, invalid_api_key, expired_api_key and revoked_api_key. A 403 is never returned for an authentication problem — see Errors.