Make your first API request

Use the sandbox to confirm that your API key works and learn the shape of a Goodstack response. This request lists countries with supported nonprofit registries. It does not create or change data.

Before you start

You need a Goodstack partner account and a publishable API key. In the Partner dashboard, copy the key from the API Keys area.

Goodstack issues two key types:

Key	Prefix	Where to use it
Publishable key	pk_	Endpoints that explicitly accept a publishable key. It can be used in front-end code.
Secret key	sk_	Server-to-server requests only. Never expose it in browser code, mobile apps, logs, or source control.

Pass either key as the raw value of the Authorization header. Do not add Bearer or another prefix.

1. Choose an environment

Use the sandbox while you build and test.

Environment	Base URL	Use it for
Sandbox	https://sandbox-api.goodstack.io	Development and integration testing
Production	https://api.goodstack.io	Live traffic after your integration is ready

The examples on this page use the sandbox.

2. Set your sandbox credentials

Set local environment variables so the key does not become part of the command itself:

export GOODSTACK_API_BASE_URL='https://sandbox-api.goodstack.io'
export GOODSTACK_API_KEY='<publishable-key>'

Replace <publishable-key> with your sandbox publishable key. Do not commit a real key to your repository.

3. List supported countries

curl --request GET \
  --url "$GOODSTACK_API_BASE_URL/v1/countries?hasRegistry=true" \
  --header "Authorization: $GOODSTACK_API_KEY" \
  --header 'Accept: application/json'

A successful request returns 200 OK and a response shaped like this:

{
  "data": [
    {
      "code": "GBR",
      "name": "United Kingdom",
      "hasRegistry": true,
      "endonyms": {
        "en": "United Kingdom"
      }
    }
  ],
  "object": "country"
}

The actual response contains every supported country that currently has registry data.

Troubleshoot the request

• 401 Unauthorised — Check that the Authorization header contains the raw sandbox key and that the key has no extra whitespace.
• 403 Forbidden — The key is valid but its partner account does not have access to the endpoint. Contact your Goodstack implementation contact.
• Connection or DNS error — Confirm that you are using https://sandbox-api.goodstack.io and that your network permits outbound HTTPS.

Next steps

• Choose an end-to-end integration guide for verification or donations.
• Browse the API reference for endpoints, parameters, and schemas.
• Download the canonical OpenAPI document for code generation or local tooling.