API Keys & Authentication

Complete developer guide for authenticating HTTP requests, handling API keys, and error handling.

The Niravai REST API uses API Keys to authenticate requests. You can manage your API keys from the Niravai Dashboard under Organization Settings.

Quick Reference

Parameter	Type	In	Description
`x-api-key`	`string`	Header	(Recommended) Your secret API Key (starts with `STD_`)
`Authorization`	`string`	Header	Alternative authentication (`Bearer STD_...`)
`x-org-id`	`string`	Header	(Optional) Target Organization ID (e.g. `org_...`)

1. Generating an API Key

Log in to the Niravai Dashboard.
Navigate to Organization Settings -> API Keys (/org/api-keys).
Click Create New API Key.
Enter a descriptive name (e.g., Production Server Integration).
Copy your generated raw API Key string (format: STD_...).

Keep your keys secret

Your API Key gives full access to your organization's resources and credits. Never expose API keys in client-side code, public GitHub repositories, or browser JavaScript.

2. Authentication Methods

Method 1: x-api-key

Pass your API key in the x-api-key request header:

GET /api/v1/products HTTP/1.1
Host: niravai.com
x-api-key: STD_a1b2c3d4e5f678901234567890abcdef

Method 2: Authorization Bearer

Pass your API key as a standard Bearer token:

GET /api/v1/products HTTP/1.1
Host: niravai.com
Authorization: Bearer STD_a1b2c3d4e5f678901234567890abcdef

3. Response & Error Handling

The API returns standard HTTP status codes along with a consistent JSON error object.

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "prod_12345",
      "name": "Denim Jacket",
      "sku": "JKT-DENIM-001"
    }
  ]
}

Missing API Key (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API Key in headers"
  }
}

Invalid API Key (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API Key"
  }
}

Missing Org Context (400 Bad Request)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing Organization ID context"
  }
}

4. Security Checklist

Environment Variables: Always store your key in .env.local or secret management tools (process.env.NIRAVAI_API_KEY).
Server-Side Execution: Execute requests only from server environments (Node.js, Next.js Server Components, Python backends).
Immediate Revocation: If a key is leaked or compromised, revoke it immediately from the API Keys management dashboard.