# Getting started with the Porkbun API

This walks you from zero to your first authenticated call in a few minutes.

## 1. Create API keys

Go to **[porkbun.com/account/api](https://porkbun.com/account/api)** and create a key. You get two values:

- a **public** key, `pk1_…`
- a **secret** key, `sk1_…`

Treat the secret like a password. Keys work whether or not your account has two-factor authentication enabled — you never have to weaken account security to automate.

> **Tip for agents:** create a *dedicated* key (not your master key) and restrict it — each key can be limited to specific source IPs (CIDR supported) and/or specific domains from the gear icon next to the key. A leaked scoped key can only touch the domains you listed, from the network you expect.

## 2. Authenticate

Two interchangeable ways to send credentials on every request:

- **Headers (preferred for GET and agent frameworks):** `X-API-Key: pk1_…` and `X-Secret-API-Key: sk1_…`
- **JSON body:** `"apikey": "pk1_…"`, `"secretapikey": "sk1_…"`

> **Gotcha:** the secret field is **`secretapikey`**, not `secretkey`. Naming it `secretkey` means the secret is never read — you'll get `MISSING_SECRETAPIKEY` (or, on older builds, `INVALID_API_KEYS_002`), which looks like a bad key but is really a field-name typo.

All requests must use HTTPS. Base URL: `https://api.porkbun.com/api/json/v3`

## 3. Make your first call

`/ping` verifies your credentials and returns your caller IP:

```bash
curl -X POST https://api.porkbun.com/api/json/v3/ping \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

```json
{ "status": "SUCCESS", "yourIp": "203.0.113.10" }
```

A `status` of `SUCCESS` means your keys are valid. Every response also carries an `X-Request-Id` header (and `requestId` body field) for support/log correlation, and an `X-API-Version` header.

## 4. Opt domains in to API access

By default each domain must be opted in to API access individually (Domain Management → Details). To manage **all** domains — including future ones — turn on **Opt In All Domains** on the [API settings page](https://porkbun.com/account/api). The `api_access=yes` filter on `/domain/listAll` returns only the domains a key can actually operate on.

## Next

- [Register a domain end-to-end](https://porkbun.com/llms/guides/register-a-domain)
- [Dynamic DNS](https://porkbun.com/llms/guides/dynamic-dns)
- [Receive and verify webhooks](https://porkbun.com/llms/guides/verify-a-webhook)
- Full endpoint reference: https://porkbun.com/llms-full.txt


---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://github.com/oborseth/Porkbun-MCP (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api