Roles and data access

Roles and capabilities

Golden authorizes users and access tokens with three built-in roles. An identity can hold more than one role; the permissions from its assigned roles are combined.

Golden does not support custom roles or individual permission keys. Use the built-in role set that gives the caller the least access its workflow needs.

Roles are global; access to data is not. A role says what kind of operation a caller may perform. A data scope says which entities, and which rows of an entity, they may perform it on. Both have to permit an operation for it to succeed.

A STEWARD granted one entity is still a steward — scoping narrows where the role applies, never what it may do. Administrators are not scoped.

Built-in roles

The important boundary is that STEWARD is not a configuration administrator. Creating entities or tables, saving resources, running table data operations, and managing task schedules require ADMIN.

Common operations by role

This table summarizes the supported surface. Confirm the documented operation and, where enabled, the running environment’s interactive explorer for the target release.

Access to entity records and duplicate groups is additionally subject to the caller’s data scope. Global operations such as file management retain their role requirements. An entity granted to nobody is visible to nobody but an administrator, whatever role the caller holds.

Choose roles for integrations

Do not assign ADMIN to a read-only integration for convenience. If one workflow needs both reading and administration, consider separate tokens so the routine read path does not carry administrative access.

Verify the assigned roles

Call GET /api/security/whoami with the credential you plan to use. The response identifies the caller type and its roles set.

Then call GET /api/data-scopes/me with the same credential to see which entities and rows it reaches. A 403 and an empty result are different diagnoses: a 403 means the role does not permit the operation, while an empty or missing result usually means the data scope does not reach that data.

Data access

A role says what kind of operation a caller may perform. A data scope says which data they may perform it on. The two are independent, and both have to permit an operation for it to succeed.

Managing data scopes requires ADMIN, in Administration → Data access or through /api/data-scopes and /api/entities/{entity}/access.

The two levels

An entity that has been granted to nobody is visible to nobody but an administrator. Golden is explicit about that rather than showing an empty screen:

Nothing here has been granted to you. Golden shows an entity — and its tables, its records and its duplicates — only when it has been granted to you. It is not a fault of your account and nothing on this screen can change it: an administrator grants access on each entity.

A denied read reports the same sentence for a record as for an entity: “This is not available to you. Either it is not there, or it has not been granted to you.” That ambiguity is deliberate — it keeps the existence of a record from leaking to somebody who cannot see it.

Grant access to an entity

Read who currently has it:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_ADMIN_TOKEN}" \
  "${GOLDEN_URL}/api/entities/sample-customer-entity/access"

For example, after configuring province as the scope column and granting two users access (these grants are not the initial sample configuration):

{
  "entity": "sample-customer-entity",
  "scopeColumn": "province",
  "scopeIndexState": "VALID",
  "principals": [
    { "principalType": "USER", "principalId": "u-…", "principalName": "A steward", "values": ["Madrid", "Toledo"] },
    { "principalType": "USER", "principalId": "u-…", "principalName": "Another steward", "values": null }
  ]
}

The first principal sees only the customers whose province is Madrid or Toledo. The second, with values: null, sees the whole entity.

PUT to the same path takes {"principals": [...]} and replaces the list. Read the current list, apply the intended change, and submit the complete result. Omitted principals lose their grants.

Use values: null to grant the whole entity. A non-null list is a row grant; [] is not a whole-entity grant. A row grant requires a configured scope column. Read the effective scope afterwards and test with the target identity.

Choose a scope column

The scope column is the entity column whose values partition the data — a region, a business unit, a brand. In the Aurelia Utilities sample, province is the natural choice: it holds twenty distinct values across the 378 customers.

curl --fail-with-body --silent --show-error \
  --request PUT \
  --header "Authorization: Bearer ${GOLDEN_ADMIN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"column":"province"}' \
  "${GOLDEN_URL}/api/entities/sample-customer-entity/scope-column"

To see what values are available to grant:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_ADMIN_TOKEN}" \
  "${GOLDEN_URL}/api/entities/sample-customer-entity/scope-values"

For example, with province configured as the scope column:

{
  "entity": "sample-customer-entity",
  "column": "province",
  "values": ["A Coruña", "Alicante", "Asturias", "Barcelona", "…", "Valladolid", "Zaragoza"],
  "truncated": false
}

Check truncated. A column with many distinct values returns a partial list, and a value missing from it is not a value that cannot be granted.

Scope index state

Setting a scope column starts a concurrent index build. The PUT answers immediately with scopeIndexState: "BUILDING", and the state becomes VALID when the build completes.

Row filtering applies while the index is unavailable. A FAILED state can affect query performance; it does not remove the caller’s data restrictions.

Check what a caller can see

Any fully authenticated caller can read their own effective scope:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/data-scopes/me"

An administrator receives an empty object: administrators are not scoped.

Bootstrapping an existing deployment

POST /api/data-scopes/bootstrap

This migration operation grants whole-entity access to every non-ADMIN principal without an existing scope. Review its access impact before running it. Afterward, restrict grants to the entities and rows each principal needs.

What data scopes do not cover

• Daily snapshots and on-demand measurements are table-wide. They report aggregateScope: ENTITY whatever the caller’s scope, so a person restricted to part of a table still sees aggregates over all of it. See Monitor product metrics.
• Roles remain global. A STEWARD scoped to one entity is still a steward on that entity; scoping does not downgrade what they may do, only where.
• Administrators are unscoped by design.

Related reading

• Access tokens
• Manage users
• Golden API endpoints

Quality measurements

ADMIN can request a measurement with POST /api/quality/measurements and follow its background run. STEWARD and VIEWER cannot start it. All three roles can read saved measurements when they have access to the table; a restricted row scope does not narrow these aggregates. See Quality metrics.