Skip to content

authentication.mdx

Latest commit

 

History

History
84 lines (62 loc) · 3.72 KB

authentication.mdx

File metadata and controls

84 lines (62 loc) · 3.72 KB
Raw
title Authenticate with the Noteboxd API
sidebarTitle Authentication
description Noteboxd uses project API keys passed as a Bearer token. Learn how to get your key, pass it correctly, and handle auth errors.

Noteboxd authenticates every request using an API key passed in the Authorization header as a Bearer token. Keys are scoped to projects so you can separate access by application. Prepaid balance is one balance per account, shared by every project on that account. There are no OAuth flows or session cookies — just a single header on every request.

Getting your API key

Your API key lives in the Noteboxd developer dashboard. To retrieve it:

Go to [developers.noteboxd.com](https://developers.noteboxd.com) and sign in with your Noteboxd account. From the dashboard home, create a new project or click into an existing one. Each project has its own API keys. Billing is not per project: every key on the account draws from the same prepaid balance. In the **Keys** section, create a key. The full secret is shown once, at creation, and is prefixed with `nb_live_`. Copy it then and store it somewhere secure. Opening the Keys section later does not reveal the secret again. If you lose it, create a new key and update your integration.

Using your API key

Pass your API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer nb_live_YOUR_KEY

Here's a complete curl example that fetches the full record for a fragrance by its canonical ID:

curl https://api.noteboxd.com/v1/fragrances/chanel-no-5 \
  -H "Authorization: Bearer nb_live_YOUR_KEY"

Replace nb_live_YOUR_KEY with your actual project key. Every endpoint in the Noteboxd API requires this header — requests without it will be rejected with a 401 error.

Security best practices

Never expose your API key in client-side code, public repositories, or anywhere it could be read by third parties. If your key is compromised, rotate it immediately from the Keys section of your project dashboard.

Store your key in an environment variable and reference it in your code rather than hardcoding it:

export NOTEBOXD_API_KEY=nb_live_YOUR_KEY
const key = process.env.NOTEBOXD_API_KEY;

This keeps your key out of version control and makes it easy to rotate without changing your code.

Auth errors

If something goes wrong with authentication, the API returns a JSON error response with a machine-readable code field. Here are the auth-related errors you may encounter:

Code HTTP Status Meaning
MISSING_API_KEY 401 No Authorization header was included in the request.
INVALID_API_KEY 401 The key was malformed, has been revoked, or does not exist.
INSUFFICIENT_BALANCE 402 The account's prepaid balance is less than the cost of this call. Top up to resume that request.
WRONG_KEY_TYPE 401 A hosted MCP or account key was sent to the commercial API, or a portal API key was sent to hosted MCP. Use the key type that matches the surface you are calling.

All error responses follow the same shape:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided does not match any active project key."
  }
}
If you receive an `INSUFFICIENT_BALANCE` error, you can add funds immediately from the Billing section of your developer dashboard. See [Pricing](/concepts/pricing) for a full breakdown of per-call costs and tips on estimating and managing your balance.