Access tokens

An access token authenticates an unattended integration. Administrators control its name, assigned roles, expiry period, enabled state, and secret lifecycle.

Before you begin

• You need the ADMIN role.
• Choose the smallest role set the integration needs.
• Prepare a secret manager for the returned token value.

Create a token

expiryDays is the requested lifetime in days, from 1 to 3650. Creation defaults to 365 days when omitted. Rotation requires an explicit expiryDays. roles is an array, even when you assign only one role.

curl -sS -X POST "$GOLDEN_URL/api/security/tokens" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Customer lookup service",
        "roles": ["VIEWER"],
        "expiryDays": 90
      }'

The response’s token member is an object. Its token field is the secret: read token.token, not the wrapper object. That object also contains id, name, roles, created, expiresAt, and enabled.

Use a token

Grant the token access to the required entity through Roles and data access. A non-administrator token without grants sees no entities, even with a valid role.

Send the complete secret returned in token.token as the bearer credential. Do not add a product-specific prefix unless it is already part of that returned value.

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

Review and change tokens

List tokens:

curl -sS "$GOLDEN_URL/api/security/tokens" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN"

Update a token’s name, roles, or expiry policy:

curl -sS -X PUT "$GOLDEN_URL/api/security/tokens/$TOKEN_ID" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer lookup service","roles":["VIEWER"],"expiryDays":90}'

Enable or disable a token without deleting its record:

curl -sS -X PUT "$GOLDEN_URL/api/security/tokens/$TOKEN_ID/disable" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN"

curl -sS -X PUT "$GOLDEN_URL/api/security/tokens/$TOKEN_ID/enable" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN"

Rotate a token

Rotation replaces the secret. The response is the next opportunity to capture the new secret at token.token.

curl -sS -X POST "$GOLDEN_URL/api/security/tokens/$TOKEN_ID/rotate" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiryDays":90}'

Update the integration with the new secret as part of the same controlled change. The previous secret is rejected after rotation. Verify the new credential with a permitted read, and check that the old credential is rejected.

Delete a token

curl -sS -X DELETE "$GOLDEN_URL/api/security/tokens/$TOKEN_ID" \
  -H "Authorization: Bearer $GOLDEN_ADMIN_TOKEN"

Use disable for a temporary suspension and delete when the integration is retired. Give each integration its own token so either action has a contained impact.

Related reading

• Authenticate with Golden
• Roles and permissions
• Golden API conventions