Authenticate with Golden

Human users sign in with a Golden-managed password or an identity-provider token, depending on the deployment. Unattended callers should use an access token instead of storing a user’s password.

Human users should follow Sign in and verify Golden access for the browser sign-in, SSO, password recovery, identity check, and sign-out experience. The API examples below are for programmatic session flows.

Set GOLDEN_URL to your service URL. The examples use curl and jq; obtain secrets through your environment’s approved prompt or secret manager.

Sign in with a Golden-managed password

jq -n --arg email "jane.smith@example.com" --arg password "$GOLDEN_PASSWORD" \
  '{email:$email,password:$password}' | \
curl --fail-with-body --silent --show-error "$GOLDEN_URL/api/security/auth" \
  -H "Content-Type: application/json" --data-binary @-

The response identifies the user and includes the session token. Treat every returned credential as a secret. Send the session token on subsequent calls:

curl -sS "$GOLDEN_URL/api/entities" \
  -H "Authorization: Bearer $GOLDEN_SESSION_TOKEN"

Do not put a password or returned token in source control, documentation, or logs. Read passwords from a protected prompt or secret store.

Sign in with an identity-provider token

Some deployments enable an external OpenID Connect provider. Obtain the token through the sign-in flow approved for that environment, then submit it in the token field:

jq -n --arg email "jane.smith@example.com" --arg token "$OPENID_TOKEN" \
  '{email:$email,token:$token}' |
curl --fail-with-body --silent --show-error "$GOLDEN_URL/api/security/auth" \
  -H "Content-Type: application/json" --data-binary @-

Provider availability and account provisioning are deployment-specific. An administrator must ensure the Golden user and its role assignment are ready; do not assume first sign-in creates or authorizes an account.

Inspect the current identity

Use whoami to verify which credential is active and which roles it carries:

curl -sS "$GOLDEN_URL/api/security/whoami" \
  -H "Authorization: Bearer $GOLDEN_SESSION_TOKEN"

This operation reports the current identity. It does not create or exchange a credential.

Refresh a session

A successful sign-in returns a session token and a refreshToken. Keep both secret. Use the refresh token to request renewed session credentials:

jq -n --arg refreshToken "$GOLDEN_REFRESH_TOKEN" '{refreshToken:$refreshToken}' |
curl --fail-with-body --silent --show-error "$GOLDEN_URL/api/security/auth/refresh" \
  -H "Content-Type: application/json" --data-binary @-

Store the returned credentials in place of the previous pair. If refresh is rejected, sign in again; do not log credentials while investigating the error.

Sign out

Signing out revokes the user’s refresh tokens across devices. An already-issued session JWT remains valid until it expires; logout does not immediately revoke that JWT:

curl -sS -X POST "$GOLDEN_URL/api/security/auth/logout" \
  -H "Authorization: Bearer $GOLDEN_SESSION_TOKEN"

Discard locally held session credentials after signing out. Access tokens are integration credentials and do not use this session logout operation.

Change or reset a password

In the web application, open Profile to update your own details or change your password. These self-service actions do not require an administrator.

A signed-in internal user can change their own password. The request body is plain text:

curl -sS -X PUT "$GOLDEN_URL/api/security/users/password/my" \
  -H "Authorization: Bearer $GOLDEN_SESSION_TOKEN" \
  -H "Content-Type: text/plain" \
  --data "$NEW_PASSWORD"

Follow the password policy shown by your deployment; its configured policy is authoritative.

Request a reset message without an authenticated session:

curl -sS -X PUT "$GOLDEN_URL/api/security/password/reset/jane.smith@example.com"

Complete the reset with the token delivered through the configured recovery channel:

jq -n --arg token "$RESET_TOKEN" --arg password "$NEW_PASSWORD" \
  '{token:$token,password:$password}' |
curl --fail-with-body --silent --show-error "$GOLDEN_URL/api/security/password/update" \
  -H "Content-Type: application/json" --data-binary @-

Recover from common failures

Related reading

• Access tokens
• Roles and permissions
• Manage users