How GoDaddy APIs work

Overview

This page explains the architecture and design principles shared across GoDaddy REST APIs — how authentication works, how environments are separated, and what to expect from API behavior. Read this before you build to ensure you have a full understanding of how GoDaddy APIs are structured.

API architecture

GoDaddy APIs are REST APIs that accept JSON request bodies and return 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 <GODADDY_PAT> 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. Scopes are additive: a single token can carry multiple scopes, and a token is limited to exactly what its scopes allow — even if the underlying account has broader access.

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.

Scopes follow the pattern api.resource:operation. For example, domains.domain:read grants read access to domain resources, and commerce.order:complete grants the ability to finalize an order. Go to Domains API concepts or Commerce core concepts for the scope tables for each API.

Go to Authenticate for the full scope reference, or How to Authenticate for token creation steps.

Legacy credentials

The older sso-key credential format (sso-key <GODADDY_KEY>:<GODADDY_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.

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 11990000 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": "RESOURCE_NOT_FOUND",
  "message": "The requested resource could not be found.",
  "fields": []
}

The code field is the machine-readable identifier to branch on. The HTTP status code alone is not sufficient — two 422 responses with different code values require different handling.

Go to Handle errors for the full error reference, status code guide, and retry semantics.

Last updated on