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

# NameGrid API Authentication: Keys, Scopes, and Errors

> NameGrid authenticates via API keys in the x-api-key header. Learn how to generate keys, scope them to workspaces, and handle auth errors.

NameGrid authenticates every request using an API key that you pass in the `x-api-key` request header. There are no OAuth flows or session tokens — just a single long-lived key that you generate in the dashboard and include with each call. Keep your keys secret and rotate them promptly if they are ever exposed.

## Generating an API key

1. Sign in to your dashboard at [app.namegrid.org](https://app.namegrid.org).
2. Navigate to **Settings → API tokens**.
3. Click **Create token** and give it a descriptive name (e.g. `production`, `staging`, or `ci-pipeline`).
4. Copy the key from the confirmation screen.

<Warning>
  Your raw API key is shown **only once** at the moment of creation. NameGrid stores only a cryptographic hash of the key, so it cannot be retrieved later. If you lose your key, revoke it immediately from **Settings → API tokens** and generate a new one.
</Warning>

API keys follow this format:

```
ng_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

## Using your API key in requests

Pass your key in the `x-api-key` header on every request. The examples below show how to do this in common environments.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.namegrid.org/v1/domains \
    -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  BASE_URL = "https://api.namegrid.org/v1"

  headers = {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
  }

  response = requests.get(f"{BASE_URL}/domains", headers=headers)
  print(response.json())
  ```
</CodeGroup>

Never include your API key in client-side code, public repositories, or URLs. Use environment variables or a secrets manager to inject the key at runtime.

## Workspace scope

Each API key is scoped to the workspace it was created in. A request made with a key from Workspace A can only read and modify resources — domains, DNS records, and account details — that belong to Workspace A.

If you send a request for a domain that belongs to a different workspace, the API returns **404 Not Found** rather than 403 Forbidden. This behavior is intentional: revealing that a resource exists but is forbidden would leak information about another customer's workspace. Treat 404 responses as "not found or not accessible."

## Rate limits

<Note>
  NameGrid enforces a rate limit of **30 requests per 60 seconds** per API key. If you exceed this limit, the API returns `429 Too Many Requests`. Wait for the current 60-second window to reset before retrying, or distribute load across multiple keys if your use case requires higher throughput.
</Note>

## Error codes

| Status | Meaning                                                                                                                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | **Bad Request** — Your request body is missing a required field or contains an invalid value. Check the `error` field in the response for details.                                                       |
| `401`  | **Unauthorized** — The `x-api-key` header is missing or the key is invalid. Verify your key and ensure the header name is correct.                                                                       |
| `402`  | **Payment Required** — Your account has insufficient credits to complete the operation. The response includes `required` (credits needed) and `balance` (your current balance) fields alongside `error`. |
| `404`  | **Not Found** — The requested resource does not exist in your workspace, or it belongs to a different workspace.                                                                                         |
| `409`  | **Conflict** — The domain is already registered or a conflicting record already exists.                                                                                                                  |
| `429`  | **Too Many Requests** — You have exceeded the rate limit of 30 requests per 60 seconds.                                                                                                                  |
| `502`  | **Bad Gateway** — A temporary upstream error occurred with the registry. Wait a few seconds and retry the request.                                                                                       |