> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomiq.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating with the Nomiq API Using API Keys Securely

> Generate a Nomiq API key, attach it as a Bearer token on every request, and keep your credentials secure using environment variables and key rotation.

Nomiq authenticates every inbound API request using HTTP Bearer tokens in the form of API keys. There are no session cookies, OAuth flows, or temporary tokens to manage — you generate a key once in the Dashboard, store it securely in your environment, and include it in the `Authorization` header of every request you make. This page walks you through exactly how to do that, what the two key types mean, and how to keep your credentials safe.

## Finding and Generating API Keys

API keys are created and managed in the Nomiq Dashboard under **Workspace Settings → API Keys**. Click **Create New Key**, give it a descriptive label (for example, `production-backend` or `ci-pipeline`), and copy the full key value immediately — Nomiq will only display the secret once. If you navigate away before copying, revoke the key and generate a fresh one.

You must be on an **Agency** or **Pro** billing tier to generate API keys. Free tier accounts do not have API access enabled.

## Test Keys vs. Live Keys

Nomiq provides two classes of API key to keep your development and production environments fully isolated.

| Key Type | Prefix        | Base URL               | Asset Output                | Billing            |
| -------- | ------------- | ---------------------- | --------------------------- | ------------------ |
| Test     | `sk_test_...` | `sandbox.nomiq.com/v1` | Watermarked, non-production | Not metered        |
| Live     | `sk_live_...` | `api.nomiq.com/v1`     | Production-ready vectors    | Metered and billed |

Use Test keys for all local development, automated testing, and CI/CD pipelines. Switch to a Live key only in your production deployment. Test key usage is completely free and does not affect your monthly quota.

<Warning>
  Never use a Live key (`sk_live_...`) in your local development environment or CI/CD test suite. Every request made with a Live key is metered and billed to your workspace. Automated test suites that fire dozens of requests per run can accumulate significant charges quickly.
</Warning>

## Passing Your API Key in Requests

Include your API key in the `Authorization` header of every HTTP request as a Bearer token. The format is always `Authorization: Bearer <your_key>` — note the single space between `Bearer` and your key value.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.nomiq.com/v1/projects" \
    -H "Authorization: Bearer $NOMIQ_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  import { Nomiq } from '@nomiq/node';

  // The SDK automatically attaches the Authorization header to every request.
  const nomiq = new Nomiq({
    apiKey: process.env.NOMIQ_API_KEY,
  });

  const projects = await nomiq.projects.list();
  console.log(projects.data);
  ```

  ```python Python theme={null}
  import nomiq
  import os

  # Initialize the client once; it handles all header injection internally.
  client = nomiq.Client(
      api_key=os.environ.get("NOMIQ_API_KEY")
  )

  projects = client.projects.list()
  print(projects.data)
  ```
</CodeGroup>

## Storing Keys Securely

The single most important security rule is: **never commit an API key to source control.** Beyond that, follow these practices to keep your credentials safe across every environment.

**Use environment variables.** Store your key in a `.env` file locally and in your host's secret management system (for example, AWS Secrets Manager, Heroku Config Vars, or Vercel Environment Variables) in production. Load it into your application at runtime — never at build time.

```bash .env theme={null}
NOMIQ_API_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
```

Ensure `.env` is listed in your `.gitignore` before your first commit:

```bash Terminal theme={null}
echo ".env" >> .gitignore
```

**Proxy all requests through your backend.** Never embed a Nomiq API key in a client-side application — a React SPA, mobile app, or browser extension. Any key visible in client-side code or network traffic can be extracted and misused by third parties. Route all Nomiq calls through a server you control.

**Scope keys by environment and service.** Create separate keys for each deployment environment (development, staging, production) and for each distinct service or pipeline that calls Nomiq. This way, if one key is compromised, you can revoke it without disrupting other services.

## Authentication Error Codes

The table below covers every authentication-related HTTP status code you may encounter, along with its most common cause and the recommended fix.

| HTTP Status | Error Code           | Cause                                                                                           | Resolution                                                                                                                       |
| ----------- | -------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401`       | `missing_api_key`    | No `Authorization` header was sent with the request.                                            | Add `Authorization: Bearer <key>` to your request headers. Verify your environment variable is resolving to a non-empty string.  |
| `401`       | `invalid_api_key`    | The key value is malformed, has been revoked, or does not exist.                                | Check that you copied the full key from the Dashboard. If it was revoked, generate a new one.                                    |
| `401`       | `wrong_environment`  | A Test key was sent to `api.nomiq.com`, or a Live key was sent to `sandbox.nomiq.com`.          | Ensure your key prefix matches your target base URL. `sk_test_...` → `sandbox.nomiq.com/v1`; `sk_live_...` → `api.nomiq.com/v1`. |
| `403`       | `billing_hard_limit` | The workspace associated with this key has exceeded its monthly quota or has an unpaid invoice. | Log into the Nomiq Dashboard, navigate to **Billing**, and resolve the outstanding payment or quota issue.                       |

## Key Rotation Workflow

If you suspect a key has been compromised, rotate it immediately using this zero-downtime procedure.

<Steps>
  <Step title="Generate a Replacement Key">
    In the Nomiq Dashboard, navigate to **Workspace Settings → API Keys** and click **Create New Key**. Label it clearly (for example, `production-backend-2`) and copy the value immediately.
  </Step>

  <Step title="Deploy the New Key">
    Update the `NOMIQ_API_KEY` environment variable in your production environment to the new key value and restart your application or trigger a redeployment. Confirm that requests are succeeding with the new key before proceeding.
  </Step>

  <Step title="Revoke the Old Key">
    Return to **Workspace Settings → API Keys**, find the old key, and click **Revoke**. Any request that still carries the old key will immediately receive a `401 Unauthorized` response.
  </Step>
</Steps>

<Warning>
  Never commit API keys to source control — not even in private repositories. Nomiq's automated security scanners continuously monitor public GitHub repositories for leaked `sk_live_...` keys. If one is detected, it is revoked automatically and you will receive an email alert. Treat a committed key as fully compromised regardless of repository visibility.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference Overview" icon="book" href="/api-reference/overview">
    Review base URL conventions, pagination parameters, and idempotency headers used across all endpoints.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limits">
    Understand per-plan request limits and how to handle 429 errors gracefully in your integration.
  </Card>
</CardGroup>