# How GoDaddy APIs work (https://developer.godaddy.com/en/docs/api-users/how-godaddy-apis-work)



## Overview

This page explains the architecture and design principles behind the GoDaddy Domains API (how authentication works, what the different API versions do, how environments are separated, and what to expect from the API's behavior). Read this before you build to ensure you have a full understanding of the GoDaddy Domain API.

## API architecture

The GoDaddy Domains API is a REST API that accepts JSON request bodies and returns JSON responses. All requests go to a single base URL (`api.godaddy.com` for production), and all API calls require an `Authorization` header carrying a Bearer token.

<Mermaid
  chart="
graph TD
App[Your application] -->|HTTPS + Bearer token| GW[api.godaddy.com]
GW --> Auth[Authentication layer]
Auth -->|Valid| Router[API router]
Auth -->|Invalid| E401[401 Unauthorized]
Router --> V1[v1 endpoints]
Router --> V2[v2 endpoints]
Router --> V3[v3 endpoints]
"
/>

Every API call follows the same pattern:

1. Include `Authorization: Bearer <token>` in the request header.
2. The gateway validates the token and checks its scopes.
3. A valid request is routed to the correct API version and resource handler.
4. The handler returns a JSON response with a standard HTTP status code.

There is no API key rotation scheme, no HMAC signing, and no session management. Every request is independently authenticated with the Bearer token.

## Authentication model

GoDaddy uses Personal Access Tokens (PATs) for API authentication. A PAT is a long-lived credential tied to a GoDaddy account with a configurable set of capability scopes.

### Why scopes matter

Scopes determine what a token can do, not just who it belongs to. A token with only `domains.domain:read` can call read endpoints but will receive `403 Forbidden` on any write operation (even if the account itself has full access). Scopes are additive: a single token can carry multiple scopes.

The scope model exists so that integrations can be given the minimum permissions they need. A read-only analytics pipeline doesn't need write scopes. A DNS automation tool doesn't need purchase scopes. The following table describes the permissions each scope grants.

| Scope                        | What it grants                               |
| ---------------------------- | -------------------------------------------- |
| `domains.domain:read`        | Read domains, DNS records, domain detail     |
| `domains.domain:create`      | Register domains (purchase)                  |
| `domains.domain:update`      | Update domain settings, contacts, lock state |
| `domains.dns:update`         | Create and delete DNS records                |
| `domains.nameserver:update`  | Replace authoritative nameservers            |
| `domains.registration:write` | Transfer domains in                          |

Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) for the full scope reference and token creation steps.

### Legacy credentials

The older `sso-key` credential format (`sso-key <key>:<secret>`) is still supported for v1 API endpoints but is scheduled for deprecation in 2026. New integrations should use PATs exclusively. PATs are required for all v3 endpoints.

## API versions

GoDaddy exposes three major API versions simultaneously. They aren't interchangeable. Different capabilities live in different versions, and the versions have different authentication requirements. The following table provides information about the available versions.

| Version | Base path                                | Auth           | Status             | Primary use                                       |
| ------- | ---------------------------------------- | -------------- | ------------------ | ------------------------------------------------- |
| v1      | `/v1/domains/...`                        | PAT or sso-key | Stable, maintained | List domains, renewals, contacts, transfers, lock |
| v2      | `/v2/customers/{customerId}/domains/...` | PAT or sso-key | Stable, maintained | Async operations, forwarding                      |
| v3      | `/v3/domains/...`                        | PAT only       | Current            | Registration, DNS records, availability checks    |

### Why three versions exist

The API has evolved over years of product development. Rather than breaking existing integrations, GoDaddy maintains older versions alongside newer ones.

* **v3** is the current version for new capabilities. It uses resource-oriented paths and returns structured, consistent responses. New features land here first.
* **v1** covers operations that haven't migrated to v3 yet ( like domain listing, contacts, renewals, transfers, and lock management). Expect these to migrate to v3 over time.
* **v2** adds async operations.

The practical rule: use v3 where available; fall back to v1 or v2 where v3 doesn't cover the operation yet. The guide pages in this section note which version each operation uses.

## Environments

GoDaddy provides a single production environment for API development. Some API calls require a funded payment method, can incur costs, and create real domain records. Scope your calls carefully. Actions taken in production are real, billable, and often irreversible.

## Request and response format

All API requests and responses use JSON. A few conventions apply across the entire API surface:

**Content-Type**: Always send `Content-Type: application/json` on requests with a body.

**Accept**: Send `Accept: application/json` on read requests. The API defaults to JSON but specifying it is good practice.

**Monetary values**: Prices are expressed in currency micro-units — multiply by 10⁻⁶ to get the currency value. A `price` of `1199000` in `USD` is `$11.99`.

**Timestamps**: All timestamps are ISO 8601 in UTC (for example, `2026-03-15T00:00:00.000Z`).

**Pagination**: v1 list endpoints use `limit` and `marker` for cursor-based pagination. v3 list endpoints use `page` and `pageSize`. Go to [Pagination](https://developer.godaddy.com/docs/api-users/pagination) for examples.

## Rate limits

The API enforces per-credential rate limits. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait.

Rate limits apply per credential. If you have multiple integrations using the same PAT, their request rates are pooled. Use separate PATs for independent workloads if you expect them to approach the limit independently.

Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current limits and handling guidance.

## Error structure

All errors return a consistent JSON envelope regardless of the HTTP status code:

```json
{
  "code": "DOMAIN_NOT_AVAILABLE",
  "message": "The domain you requested is not available.",
  "fields": []
}
```

The `code` field is the machine-readable identifier to branch on. The HTTP status code alone is not sufficient — a `422` with `DOMAIN_NOT_AVAILABLE` requires a different response than a `422` with `NO_PAYMENT_PROFILE`.

Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error reference, status code guide, and retry semantics.