Nippy API Platform

API key format

All Nippy keys use the npk_live_ prefix followed by a random string:

npk_live_a1b2c3d4e5f6...

Each key is tied to a specific businessId. The server resolves your business automatically from the key — you don’t need to pass it in SDK methods, but you do in direct REST API calls.

Never expose your key in client-side code (browser, mobile app). Use it only in your backend.

With the SDK

Pass it in the constructor once:

import { NippyClient } from '@nippy/sdk'

const nippy = new NippyClient({
  apiKey: process.env.NIPPY_API_KEY,  // never hardcoded
  baseUrl: 'https://ms.nippy.la'
})

The SDK includes it automatically in every request. You don’t need to manage it manually.

With direct REST API calls

For administration endpoints (creating campaigns, rules, viewing logs) that don’t go through the SDK, include both headers:

x-api-key: npk_live_xxx
x-business-id: your-business-id

Example:

curl https://ms.nippy.la/v1/public/campaigns \
  -H "x-api-key: npk_live_xxx" \
  -H "x-business-id: your-business-id"

Authentication errors

HTTP code	Cause	Fix
`401 Unauthorized`	Key invalid, expired, or missing	Verify the key is correct and in the `x-api-key` header
`403 Forbidden`	The key does not have access to the requested resource	Verify the `businessId` matches your key

import { NippyError, NippyErrorCodes } from '@nippy/sdk'

try {
  await nippy.spin({ userId, campaignId })
} catch (error) {
  if (error instanceof NippyError && error.code === NippyErrorCodes.UNAUTHORIZED) {
    // verify the API key is valid
  }
}

Best practices

Store the key in environment variables (NIPPY_API_KEY)
Rotate the key if you suspect it was compromised — contact us at support@nippy.la
Use a single NippyClient instance per process; do not recreate it per request

Start here

SDK

MCP

Authentication

API key format

With the SDK

With direct REST API calls

Authentication errors

Best practices

​API key format

​With the SDK

​With direct REST API calls

​Authentication errors

​Best practices

API key format

With the SDK

With direct REST API calls

Authentication errors

Best practices