# Porkbun API v3 — Auth

> Token-based authentication

Part of the Porkbun API v3.63. Topic index: https://porkbun.com/llms · Full reference: https://porkbun.com/llms-full.txt · Overview: https://porkbun.com/llms.txt · OpenAPI spec: https://porkbun.com/api/json/v3/spec

**Auth:** send `X-API-Key` / `X-Secret-API-Key` headers (preferred) or `apikey` / `secretapikey` in the JSON body. Create keys at https://porkbun.com/account/api

---

# Endpoints

## POST /api/json/v3/auth/login

**Login with username and password**

**Partner-only endpoint** (requires `auth:login` access on the API key). Authenticate a Porkbun account with username and password and receive a short-lived token (5 minutes). Supports TOTP and email-based 2FA. Returns HTTP 403 with a `2FA` field when a second factor is required.

**Key permission needed:** `account`

| Parameter | In | Required | Description |
|---|---|---|---|
| `Sig` | header | yes | Base64-encoded SHA-256 digest of the trimmed request body, signed with the private key associated with the API key. |
| `Idempotency-Key` | header | no | Optional, recommended on every purchase and write. Send a unique value (a UUID) per intended operation. Repeating the request with the same key and an identical body within 24 hours returns the original response instead of doing it again, so a retry after a timeout cannot double-charge or double-apply. The same key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH; while the first request is still running, 409 IDEMPOTENCY_KEY_IN_USE. |

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | string | yes |  |
| `password` | string | yes |  |
| `twoFactorCode` | string | no | TOTP or email 2FA code, if required |

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

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `token` | string | Short-lived session token (5 minutes) |
| `expiration` | string |  |

---

## 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://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api