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

***

title: How GoDaddy APIs work
description: The architecture, authentication model, environments, and request conventions shared across all GoDaddy REST APIs.
keywords: OTE, api.godaddy.com, api.ote-godaddy.com, sandbox, v1 v2 v3, sso-key vs PAT, JSON REST, Bearer token, scopes
related:
guides:

* title: "Authenticate"
  href: "/docs/api-users/auth"
* title: "Make your first call"
  href: "/docs/api-users/quickstart"
* title: "Handle errors"
  href: "/docs/api-users/errors"
* title: "Rate limits"
  href: "/docs/api-users/rate-limits"
  concepts:
* title: "Domains core concepts"
  href: "/docs/api-users/domains/concepts"
* title: "Building reliable integrations"
  href: "/docs/api-users/concepts/building-reliable-integrations"

***

## 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](https://developer.godaddy.com/docs/api-users/domains/concepts) or [Commerce core concepts](https://developer.godaddy.com/docs/api-users/commerce/concepts) for the scope tables for each API.

Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) for the full scope reference, or [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) 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](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": "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](https://developer.godaddy.com/docs/api-users/errors) for the full error reference, status code guide, and retry semantics.