Getting started

The API uses the OAuth 2.0 client_credentials grant. You exchange an API key for an access token, then send the token as a bearer token. There are no user logins or one-time codes involved: the key belongs to the tenant, not to a person.

curl -X POST https://api.noccie.app/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tk_YOUR_KEY_ID",
    "client_secret": "YOUR_KEY_SECRET"
  }'

curl -X POST https://api.noccie.app/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=tk_YOUR_KEY_ID \
  -d client_secret=YOUR_KEY_SECRET

curl -X POST https://api.noccie.app/oauth/token \
  -u tk_YOUR_KEY_ID:YOUR_KEY_SECRET \
  -d grant_type=client_credentials

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "view_product",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}

curl "https://api.noccie.app/tenant/TENANT_ID/product?type=service,set" \
  -H "Authorization: Bearer ACCESS_TOKEN"

OpenAPI specificationCopy Anchor Link

The full API is described in an OpenAPI specification: openapi.json. Use it to import all endpoints into a tool such as Postman or Insomnia, or to generate a client with a code generator. It is always in sync with this reference.

Use PostmanCopy Anchor Link

Postman has built-in support for this grant, so it can fetch and refresh the token for you.

To get all endpoints at once, import the OpenAPI specification first (Import → Link, or upload the downloaded file).

1. Open your request or collection, go to the Authorization tab and choose OAuth 2.0.
2. Under Configure New Token, fill in:

3. Click Get New Access Token, then Use Token. Postman sends it as Authorization: Bearer ....

The token response contains your tenant_id. Copy it from the token details in Postman and store it in a variable, for example {{tenantId}}, so you can call https://api.noccie.app/tenant/{{tenantId}}/product.

Token lifetime and cachingCopy Anchor Link

• A token is valid for one hour (expires_in is 3600 seconds).
• Request a token once and reuse it for all calls in that hour. Do not request a new token for every API call: the token endpoint is rate limited.
• Request a new token shortly before the old one expires, or when you get a 401 back.
• Treat the token as an opaque string. Do not read scopes or other data from inside it.

Storing the secretCopy Anchor Link

Keep the key secret in an environment variable or a secret store on your server. Never put it in source code, a repository, a browser app or a mobile app: anyone who can read it can use your key. The key belongs on a server.

Token handling patternCopy Anchor Link

• Keep one token per process in memory and reuse it.
• Refresh it a few minutes before expires_in runs out.
• On a 401, fetch one new token and retry the request once. A second 401 is a real error: the key is revoked or expired, or the scope is missing.
• On a 429, wait and retry with the same token. Do not request new tokens in a loop.
• Never log the secret or the token.

Node.js exampleCopy Anchor Link

This example needs Node.js 18 or later and no packages. Optionally set NOCCIE_API_HOST (the API host without https://, default api.noccie.app), and set NOCCIE_KEY_ID, NOCCIE_KEY_SECRET and NOCCIE_TENANT_ID in the environment, then run it with node example.js.

const { NOCCIE_KEY_ID, NOCCIE_KEY_SECRET, NOCCIE_TENANT_ID } = process.env;
const API_HOST = process.env.NOCCIE_API_HOST ?? 'api.noccie.app';
const base = `https://${API_HOST}`;

let cached = null; // { token, expiresAt }
const REFRESH_MARGIN_MS = 5 * 60 * 1000;

async function getToken(force = false) {
  if (!force && cached && Date.now() < cached.expiresAt - REFRESH_MARGIN_MS) return cached.token;

  const res = await fetch(`${base}/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: NOCCIE_KEY_ID,
      client_secret: NOCCIE_KEY_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`Token request failed: ${res.status} ${(await res.json().catch(() => ({}))).error ?? ''}`);

  const { access_token, expires_in } = await res.json();
  cached = { token: access_token, expiresAt: Date.now() + expires_in * 1000 };
  return cached.token;
}

async function apiGet(path, { retried = false, waited = false } = {}) {
  const res = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${await getToken()}` } });

  if (res.status === 401 && !retried) {
    await getToken(true); // fetch ONE new token, then retry once
    return apiGet(path, { retried: true, waited });
  }
  if (res.status === 429 && !waited) {
    const seconds = Number(res.headers.get('retry-after')) || 5;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); // reuse the same token
    return apiGet(path, { retried, waited: true });
  }
  if (!res.ok) throw new Error(`API request failed: ${res.status}`); // a second 401 is a real error
  return res.json();
}

async function main() {
  const { products } = await apiGet(`/tenant/${NOCCIE_TENANT_ID}/product?type=service,set`);
  console.log(`Received ${products.length} products`);
}

main().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

Scopes and revoking keysCopy Anchor Link

A scope is a permission on a key, such as view_product. A call only works when the key has the scope that the endpoint requires. The required scope is listed per endpoint.

The scopes are not stored in the token. NOCCIE checks the key on every request. That means:

• When a key is revoked, its tokens stop working immediately, even if they have not expired yet.
• When the scopes of a key change, the change applies immediately to existing tokens.
• When a key expires, its tokens stop working at the same moment.

Tokens only work on endpoints that are explicitly enabled for API tokens, and only for the tenant of the key.

ErrorsCopy Anchor Link

Token endpointCopy Anchor Link

Errors from POST /oauth/token have the form {"error": "<code>"}.

API endpointsCopy Anchor Link

SecurityCopy Anchor Link

• Keep the key secret on your server. Never put it in a browser, mobile app, public repository or log file.
• Use one key per integration, with only the scopes it needs, so you can revoke one without affecting the others.
• Rotate a key by creating a new key, switching your integration to it, and then revoking the old key.
• If a secret may have leaked, revoke the key right away. Its tokens stop working immediately.
• Set an expiry date on keys that are only needed temporarily.