---
title: "How to use the DNSense API with an API key"
description: "Create an API key, call the DNSense API from a script and keep the key safe. With curl examples for listing zones and adding a record."
canonical_url: "https://dnsense.io/learn/how-to-use-the-dnsense-api-with-an-api-key"
---

> Index of every page on this site: [llms.txt](https://dnsense.io/llms.txt)

Adding the same record to thirty zones by hand is the kind of job a script does better. DNSense has an API for it, and an API key is how a script signs in without your password.

## What a key can do

A key acts as you. It reaches the zones, domains and connections of the team you work in and can do what your role allows. Changes made with it appear in the zone history and the audit log, like any other.

One limit: a key cannot manage your login, two-factor or API keys. Those need you signed in to the app, so a leaked key cannot create more keys or extend itself.

## Create a key

1. Open **Account** and find **API keys**.
2. Click **Create key** and name it after where it will run, such as `CI pipeline`.
3. Copy the secret. DNSense shows it once.

Store it in your password manager or your CI's secret store. Never commit it to a repository.

## Make a request

Send the secret as a Bearer token. List the zones you can reach:

```text
curl -H "Authorization: Bearer <your key>" https://api.dnsense.io/zones
```

Add an A record to a zone:

```text
curl -X POST https://api.dnsense.io/zones/<zone id>/records \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"record": {"name": "shop", "type": "A", "content": "198.51.100.7", "ttl": 3600}}'
```

DNSense queues the change and applies it at the provider that owns the zone. An empty or missing `name` is the apex of the zone. If your team requires approval for changes, this one waits for it like it would from the app.

The full list of endpoints, with the fields each one takes, is at `https://api.dnsense.io/docs`.

## Keep keys small and separate

Make one key per job. When the pipeline is retired, you delete its key and nothing else breaks. The list shows when each key was created and last used, so a key nobody has used for months is easy to spot.

- **Disable** pauses a key. Enable it again when you need it.
- **Rotate** issues a new secret and revokes the old one immediately. Do it when someone who knew the secret leaves, and update the place where the key is used.
- **Delete** removes the key for good.

Creating, rotating, disabling and deleting a key all land in the audit log.

## If a request fails

- `401`: the key is wrong, disabled or deleted. Check the header and the key list.
- `403`: your role does not allow it. A key never has more access than you.
- `400`: a field is missing or invalid. The message names it.

## Sitemap

See the full [sitemap](https://dnsense.io/sitemap.md) for all pages.