Getting started

Requirements

• An active Storefront with API access enabled
• API credentials (Client ID and Client Secret) generated in Storefront Manager
• Your OpenSRS account balance above $10 to keep your Storefront active

Step 1: Generate your API credentials

Your API credentials are a Client ID and Client Secret pair generated from within your Storefront Manager. The Client Secret is shown only once. Store it securely before closing the window.

1. Log in to Storefront Manager.
2. Navigate to Settings → Advanced Settings → API.
3. Click Create to generate a new credential pair.
4. Confirm your login credentials when prompted, before the secret is generated.
5. A pop-up displays your Client Secret. Copy it to a secure location immediately. It will not be shown again.
6. Your Client ID is displayed in the table and can be copied at any time.

Managing your credentials

From the credentials table, you can:

• Rotate your secret: generates a new Client ID and Client Secret. You can choose a grace period (1 hour, 24 hours, 3 days, or 7 days) during which the old secret remains valid, giving you time to update your integration before the old one expires.
• Delete your credentials: immediately invalidates the Client ID and Client Secret. Any integration using these credentials stops working.

Security note: Treat your Client Secret like a password. Do not expose it in client-side code, commit it to source control, or share it. If you suspect a secret has been compromised, rotate it immediately.

Step 2: Obtain an access token

The Storefront API uses OAuth 2.0 Client Credentials, a server-to-server flow where your application authenticates using its Client ID and Secret directly, with no user login involved.

Token endpoints

Requesting a token

Send a POST request to the token endpoint for your environment, passing your credentials via HTTP Basic Auth:

curl -X POST "https://auth.shopco.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

A successful response returns your access token:

{
  "access_token": "eyJraWQiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access_token is a signed JWT valid for expires_in seconds (typically 1 hour).

Using the token

Include the token in the Authorization header on every API request:

Authorization: Bearer <access_token>

Example, production:

curl -X GET "https://api.shopco.com/v1/domain/example.com/dns_records" \
  -H "Authorization: Bearer eyJraWQiOiJ..."

Token expiry

Tokens expire after expires_in seconds. There is no refresh token in the Client Credentials flow. Simply request a new token using the same credentials.

Recommended practice: cache the token and re-request it proactively 30 to 60 seconds before expiry to avoid race conditions at the boundary.

If a request returns 401, treat it as a signal that the token has expired or been invalidated. Discard the cached token, request a new one, and retry the request once. Do not retry indefinitely.

Authentication error responses

Step 3: Make your first API call

With a valid token, you're ready to call the API.

Base URLs

All requests must be made over HTTPS. Requests over HTTP are rejected. The examples throughout this guide use the production base URL. Substitute api.test.shopco.com when testing against the test environment.

Example: list DNS records for a domain

curl -X GET "https://api.shopco.com/v1/domain/example.com/dns_records" \
  -H "Authorization: Bearer <access_token>"

A 200 OK response returns the full list of DNS records for that domain. See DNS endpoints below for the complete reference.

Rate limiting

Requests are rate limited per reseller account to 600 requests per minute. Every authenticated response includes the following headers to help you track usage:

When the rate limit is exceeded, the API returns 429 Too Many Requests.