Required Privilege for Custom Assertion API Mutations (upsertCustomAssertion and reportAssertionResult)

Area: API Issues

Sub-Area: GraphQL Mutation Authorization / Assertions API

Issue

When calling the upsertCustomAssertion or reportAssertionResult GraphQL mutations using a Personal Access Token (PAT), users may receive a 403 Forbidden error even though the token authenticates successfully. This occurs because these mutations require a specific metadata privilege on the target dataset, and common role assignments or platform-level privileges alone are not sufficient to authorize the request.

Error Messages

• 403 Forbidden
• Not authorized to perform this action

You Might Be Asking

• Why does my PAT authenticate but still return a 403 when calling upsertCustomAssertion?
• What privilege does a user need to create or update custom assertions via the API?
• Does the Editor role grant permission to use the assertions GraphQL mutations?
• Why does reportAssertionResult return a 403 even after successfully upserting an assertion?

Solution

1. Understand the required privilege.

   Both upsertCustomAssertion and reportAssertionResult use the same authorization check: the actor (the user or service account whose PAT is being used) must have the Edit Assertions privilege (EDIT_ENTITY_ASSERTIONS) on the dataset that the assertion monitors. Platform-level privileges do not satisfy this check — it must be a metadata-level privilege scoped to the relevant dataset.

   Additionally, for upsertCustomAssertion, if the assertion URN already exists and points to a different dataset, the actor must also have Edit Assertions on that previously associated dataset. If the existing dataset cannot be resolved, the request will be denied.

2. Verify the actor's role and policy assignments.

   Navigate to Settings > Permissions > Policies and confirm the following:

   • The active metadata policy covering the target dataset includes the Edit Assertions privilege.
   • The policy is active (not deactivated or removed).
   • The policy scope (resource filter) includes the target dataset — policies scoped to a subset of datasets will not apply to datasets outside that filter.

   Navigate to Settings > Permissions > Roles and confirm:

   • The user who owns the PAT has been assigned a role that includes Edit Assertions. Note that a PAT authenticates as the token owner — the token itself does not inherit permissions independently.
   • Role assignments via group membership also apply and should be verified.
3. Grant the Edit Assertions privilege (if not already present).

   If you cannot modify an existing role, create a targeted metadata policy:

   1. Go to Settings > Permissions > Policies and click Create policy.
   2. Set the policy type to Metadata.
   3. Add the Edit Assertions privilege.
   4. Scope the policy to the specific dataset(s) the assertion monitors, or leave it unrestricted for broader access.
   5. Assign the policy to the user account that owns the PAT.
   6. Save and activate the policy.
4. Test the mutations after updating permissions.

   Use the following example GraphQL calls to validate access. No new token is required — the existing PAT will reflect the updated permissions immediately after the policy is applied.

   # Example: upsertCustomAssertion
   mutation {
     upsertCustomAssertion(
       urn: "urn:li:assertion:<your-assertion-id>",
       input: {
         entityUrn: "urn:li:dataset:(<platform>,<dataset-name>,<env>)",
         type: FRESHNESS,
         description: "My custom freshness assertion",
         fieldPath: null,
         externalUrl: "https://<your-monitoring-tool>/assertion/<your-assertion-id>"
       }
     ) {
       urn
     }
   }

   # Example: reportAssertionResult
   mutation {
     reportAssertionResult(
       urn: "urn:li:assertion:<your-assertion-id>",
       result: {
         type: SUCCESS,
         externalUrl: "https://<your-monitoring-tool>/run/<your-run-id>",
         properties: []
       }
     )
   }

5. If a 403 persists after updating permissions.

   Gather the following details and contact DataHub Support for further policy evaluation:

   • The dataset URN the assertion is attached to.
   • The assertion URN (if previously upserted).
   • The actor URN (the user account that owns the PAT).
   • The name and scope of any policies that have been applied.

Additional Notes

The default Editors metadata policy in DataHub includes the EDIT_ENTITY_ASSERTIONS privilege out of the box. If your environment's Editor policy has been modified, deactivated, or scoped to exclude certain datasets, users assigned the Editor role may still receive a 403. Always verify that the policy is active and that its resource scope covers the target dataset. This behavior applies to both DataHub Cloud and self-hosted deployments. The authorization check is consistent across both upsertCustomAssertion and reportAssertionResult — there is no separate privilege for reporting results versus creating assertions.

Related Documentation

• Custom Assertions API Tutorial
• DataHub Policies and Privileges
• DataHub GraphQL API Overview
• Personal Access Tokens

Tags: custom-assertions, upsertCustomAssertion, reportAssertionResult, 403-forbidden, GraphQL, Edit-Assertions, authorization, metadata-policy, PAT, assertions-api