Create API Key

developer

POST/v1/keys

Generates a new API key with configurable name, environment (live/test), permission scopes, rate limit override, IP allowlist, and expiration date. The full key value (format: edns_{env}_{32 chars}) is returned exactly once at creation — it is hashed with SHA-256 and a unique salt before storage and cannot be retrieved again. Follows OWASP Key Management Cheat Sheet recommendations for secure key generation using crypto.getRandomValues().

What It Does

Generates a cryptographically secure API key using the Web Crypto API (crypto.getRandomValues with 32 random bytes mapped to 62-character alphanumeric alphabet). The key is immediately hashed with SHA-256 using a per-key random salt (16 bytes) before database storage — only the hash and salt are persisted. Returns the full plaintext key exactly once. Supports configuration of: name, environment (live/test for production/staging separation), permission scopes for least-privilege access, per-key rate limit override, IP allowlist for network-level restriction, and expiration date.

Why It's Useful

Dedicated API keys per application, environment, and team member are a foundational security practice. OWASP recommends unique keys per integration point with scoped permissions following the principle of least privilege. Environment separation (live vs test) prevents accidental production data access from development tools. IP allowlisting adds defense-in-depth by restricting which networks can use each key.

Use Cases

Developer

Per-Application Key Isolation

Create dedicated API keys for each microservice or application with minimum required permission scopes. A monitoring service only needs dns:read and domain:read, not write permissions.

Minimize blast radius of key compromise — a leaked monitoring key cannot modify DNS records or other write-scoped resources.

DevOps Engineer

Environment-Separated Deployment

Create separate live and test environment keys. CI/CD pipelines use test keys (free quota, isolated data), while production deployments use live keys with IP allowlisting.

Complete environment isolation — test activity never impacts production quotas or data.

Security Engineer

Contractor & Vendor Access

Create time-limited keys with IP allowlisting and restricted scopes for contractors or third-party integrations. Set expiration to match contract end date.

Automatic access expiration eliminates the risk of forgotten contractor keys persisting after engagements end.

Parameters

Name	Type	Required	Description
`domain`	string	Required	JSON request body with key configuration: name (required), environment (live\|test), permissions (scope array), rate_limit_override, ip_allowlist, expires_at (ISO 8601)Example: `{"name": "Production Monitoring", "environment": "live", "permissions": ["dns:read", "domain:read"], "ip_allowlist": ["203.0.113.0/24"]}`

Response Fields

Field	Type	Description
`key`	string	Full API key value (edns_{env}_{32 chars}) — shown ONCE only, store securely
`key_id`	string	Unique key identifier for management operations
`name`	string	Key name
`prefix`	string	Key prefix (edns_live_ or edns_test_)
`hint`	string	Last 4 characters for visual identification
`environment`	string	Key environment: live or test
`permissions`	array	Configured permission scopes
`rate_limit_override`	number\|null	Custom rate limit or null for default
`ip_allowlist`	array	Configured IP restrictions
`expires_at`	string\|null	Expiration date if set
`created_at`	string	Creation timestamp

Code Examples

cURL

curl "https://api.edgedns.dev/v1/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "domain={"name": "Production Monitoring", "environment": "live", "permissions": ["dns:read", "domain:read"], "ip_allowlist": ["203.0.113.0/24"]}"

JavaScript

const response = await fetch(
  'https://api.edgedns.dev/v1/keys?domain=%7B%22name%22%3A%20%22Production%20Monitoring%22%2C%20%22environment%22%3A%20%22live%22%2C%20%22permissions%22%3A%20%5B%22dns%3Aread%22%2C%20%22domain%3Aread%22%5D%2C%20%22ip_allowlist%22%3A%20%5B%22203.0.113.0%2F24%22%5D%7D',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    'https://api.edgedns.dev/v1/keys',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
    'domain': '{"name": "Production Monitoring", "environment": "live", "permissions": ["dns:read", "domain:read"], "ip_allowlist": ["203.0.113.0/24"]}'
    }
)

data = response.json()
print(data)

Read the full Create API Key guide

Why it matters, real-world use cases, parameters, response fields, and how to call it from Claude, ChatGPT, or Gemini via MCP.

Read the guide →

External References

Learn more about the standards and protocols behind this endpoint.

OWASP API Security RFC 7519 - JWT

Try This Endpoint

Test the Create API Key endpoint live in the playground.

Open in Playground Get API Key