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.

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.

Go to Authenticate 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.

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 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 for current limits and handling guidance.

Error structure

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

{
  "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 for the full error reference, status code guide, and retry semantics.

Last updated on