NameGrid API Authentication: Keys, Scopes, and 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

Sign in to your dashboard at app.namegrid.org.
Navigate to Settings → API tokens.
Click Create token and give it a descriptive name (e.g. production, staging, or ci-pipeline).
Copy the key from the confirmation screen.

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.

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.

curl https://api.namegrid.org/v1/domains \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"

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())

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

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.

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.

Get Started

Core Concepts

Guides

NameGrid API Authentication: Keys, Scopes, and Errors

Generating an API key

Using your API key in requests

Workspace scope

Rate limits

Error codes

​Generating an API key

​Using your API key in requests

​Workspace scope

​Rate limits

​Error codes

Generating an API key

Using your API key in requests

Workspace scope

Rate limits

Error codes