On this page

Make your first Golden API calls

Verify a Golden API connection, list available entities, and perform a safe record search in about five minutes.

Verify your Golden connection, list the deployment’s entities, and optionally run a read-only search. The first two calls make no product changes.

Before you begin

You need:

  • the HTTPS URL for a supported Golden environment;
  • a current API token with at least the VIEWER role and a grant to the target entity; and
  • curl or an equivalent HTTP client.

Ask your administrator for a non-production entity when learning the API. Do not paste tokens into source files, shell history, tickets, or documentation.

Set the connection values

export GOLDEN_URL="https://golden.example.com"
export GOLDEN_TOKEN="<token-from-your-administrator>"

GOLDEN_URL does not include the /api path. Keep the token in your current shell or secret manager and remove it when the session ends.

Verify the product connection

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Accept: application/json" \
  "${GOLDEN_URL}/api/configuration/version"

A successful response contains the version reported by the running product:

{"version":"<current-version>"}

A 401 response means the credential is absent, expired, or invalid. A 403 response means the credential is valid but cannot perform the requested operation.

List entities

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Accept: application/json" \
  "${GOLDEN_URL}/api/entities"

The response contains an entities array filtered by the caller’s grants. A non-administrator token with no grants receives an empty list. Ask an administrator to grant the intended entity; assigning a role alone does not grant its data. Choose a non-production entity that permits test searches.

Search an entity

Set the selected identifier:

export GOLDEN_ENTITY="sample-customer-entity"

Send a record-shaped search. Its fields must belong to the entity’s dataset.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "record": {
      "taxId": "12345678Z"
    },
    "options": {},
    "pageNumber": 0,
    "pageSize": 10
  }' \
  "${GOLDEN_URL}/api/golden/${GOLDEN_ENTITY}/search"

A successful response contains the submitted search record, a result array, a total count, and page information. An empty result is a successful search with no matching records.

Clean up

These requests create no data. Remove the token from the shell when finished:

unset GOLDEN_TOKEN

Next steps

Golden 3.0.0 · Published 2026-10-04