# Make your first call (https://developer.godaddy.com/en/docs/api-users/quickstart) --- title: Make your first call description: >- Make your first API call to the GoDaddy Domains API using a Personal Access Token (PAT). keywords: >- hello world, curl example, Bearer token, GODADDY_PAT, 401 unauthorized, domains v3, first request. agentNotes: permissions: - Any account scopes: - 'domains.domain:read' - 'commerce.store:read' idempotent: true destructive: false failureRecovery: >- Read-only. Safe to retry any failure. On 401, verify the Bearer token has not expired or been revoked. On 429, wait for Retry-After. related: guides: - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register - title: Manage existing domains href: /docs/api-users/domains/manage concepts: - title: Authentication href: /docs/api-users/auth - title: Error handling href: /docs/api-users/errors apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Commerce API reference href: /docs/references/rest/stores/get-store-by-id pageId: 654bad38-2db7-4558-9316-8d8a8b342dd3 --- For full API coverage, provide the [Domains v3 OpenAPI spec](https://developer.godaddy.com/openapi/domains-v3.json) as additional context to your LLM or API client. ## Overview This guide walks through making your first GoDaddy API call, using the Domains API and a Personal Access Token (PAT) sent as a Bearer token in the `Authorization` header. For other APIs that accept a PAT, only the endpoint and scope change. Not every GoDaddy API accepts a PAT. Some require a Classic Developer Key instead. Go to [About Authentication](https://developer.godaddy.com/docs/api-users/auth) for the credential each API requires. ## Prerequisites Before making any API call, you need: * a GoDaddy account * a Personal Access Token (PAT) with the appropriate scopes Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) to create a PAT. * a terminal with `curl` (macOS, Linux, or WSL) * (*optional*) [the GoDaddy CLI](https://developer.godaddy.com/docs/api-users/cli/set-up), if you prefer CLI workflows ### Additional prerequisites for Commerce * a `storeId` Sign in and copy the `storeId` from [Your Stores](https://developer.godaddy.com/docs/api-users/commerce) on the Commerce API overview. * (*for your customer's store only*) an OAuth `access_token` for that customer you obtain after the customer authorizes your third-party app. ## Set the credential as an environment variable Include the PAT as a Bearer token in the `Authorization` header on every request. Exporting it as an environment variable keeps it out of your shell history and lets you reference it directly in commands without retyping. The following procedure exports your PAT so the samples below can reuse it. * Export the credential: ```bash export GODADDY_PAT="" ``` ## Make the call All calls use a Bearer token in the `Authorization` header. Choose an API path. Only the endpoint and required scope change. **Domains** `GET /v3/domains/check-availability` takes a single `domain` query parameter and returns whether that domain can be registered, along with current pricing for each registration term. The request is read-only, so no charges apply. Your token needs the `domains.domain:read` scope. The following procedure checks whether a domain is available to register. * Run the request: ```bash tab="curl" curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch( "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com", { headers: { Authorization: "Bearer " + pat, }, } ); const result = await res.json(); console.log(result); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v3/domains/check-availability", params={"domain": "your-idea.com"}, headers={ "Authorization": "Bearer " + pat, }, ) print(res.json()) ``` ```bash tab="CLI" gddy domain available your-idea.com ``` **Commerce** `GET /v1/commerce/stores/{storeId}` fetches a single store. The request is read-only, so nothing is charged or changed, and the response includes the same `storeId` that the catalog, order, and tax endpoints require. Your token needs the [`commerce.store:read`](https://developer.godaddy.com/docs/references/rest/commerce-scopes#store) scope. Go to [Commerce API scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes) for the full list. The following procedure fetches a store on your own GoDaddy account with your PAT. 1. Replace `$STORE_ID` with your store's ID. 2. Run the request: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/commerce/stores/$STORE_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const pat = process.env.GODADDY_PAT; const res = await fetch( "https://api.godaddy.com/v1/commerce/stores/$STORE_ID", { headers: { Authorization: "Bearer " + pat, }, } ); const store = await res.json(); console.log(store); ``` ```python tab="Python" import os, requests pat = os.environ["GODADDY_PAT"] res = requests.get( "https://api.godaddy.com/v1/commerce/stores/$STORE_ID", headers={"Authorization": f"Bearer {pat}"}, ) res.raise_for_status() store = res.json() print(store["id"], store["displayName"], store["status"]) ``` ## Read the response The selected API path above stays selected here. Check that your output matches the shape for that path. **Domains** The API returns a JSON object describing availability and current pricing. `available` tells you whether the domain can be registered right now. `prices[]` contains one entry per registration term. `price.value` and `renewalPrice.value` are expressed in the smallest currency unit, such as cents for USD. Divide by 100 when displaying USD prices. The following procedure describes how to verify the Domains response. * Check that your output matches this shape. Angle-bracket values are placeholders. Your response returns real booleans, numbers, and enum strings. Only `domain` echoes the value from your request: ```json { "available": "", "definitive": "", "domain": "your-idea.com", "inventory": "", "prices": [ { "period": "", "price": { "currencyCode": "", "value": "" }, "renewalPrice": { "currencyCode": "", "value": "" }, "term": "" } ] } ``` The API might return more `prices[]` entries for additional periods. Availability and pricing are indicative; the final price is locked when you create a registration quote. **Commerce** The response is a single store object. Its `id` is the `storeId` you'll pass to the catalog, order, and tax endpoints; `displayName` and `status` tell you which store you're looking at and whether it's active. The following procedure describes how to verify the Commerce response. * Check that your output matches this shape: ```json { "id": "s1234567-89ab-cdef-0123-456789abcdef", "businessId": "b7654321-fedc-ba98-7654-3210fedcba98", "displayName": "My Online Store", "status": "ACTIVE", "timezone": "America/Phoenix", "address": { "addressLine1": "3032 Bunker Hill Lane", "adminArea2": "Scottsdale", "adminArea1": "AZ", "postalCode": "85251", "countryCode": "US" }, "createdAt": "2024-01-15T09:30:00Z" } ``` A wrong or unknown `storeId` returns `404 Not Found` — double-check the value you copied from [Your Stores](https://developer.godaddy.com/docs/api-users/commerce). ## Common errors | Error | Likely cause | Fix | | --------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Token is missing, expired, or wasn't exported | Run `echo $GODADDY_PAT` — if blank, re-run the export. If the token was deleted or expired, generate a new one in the [developer dashboard](https://developer.godaddy.com/personal-access-token). | | `403 Forbidden` | Token lacks the required scope for this API, or the account isn't eligible | Check the `code` field in the response body. Scope issues return `UNABLE_TO_AUTHENTICATE`; account issues return a different code. Regenerate the PAT with the correct scope selected. | | `429 Too Many Requests` | Rate limit exceeded | Wait for the number of seconds in the `Retry-After` header before retrying. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current values and retry guidance. | | Response is `null` or `undefined` | The JSON response wasn't awaited or parsed | Ensure you `await res.json()` in Node, or `res.json()` in Python. | | `Could not resolve host` | Wrong base URL | The API base is `https://api.godaddy.com`. There is no local dev server — all requests go to production. | Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope reference, status code semantics, and retry guidance.