Skip to content

docs(sdks): incorrect otdfctl flag and JSON shape in troubleshooting "Permission Denied" example #321

@marythought

Description

@marythought

Summary

The Permission Denied / Insufficient Entitlements section in docs/sdks/troubleshooting.mdx (lines ~228-241) shows a subject-condition-sets create example that uses an incorrect flag name and an incorrect JSON shape:

otdfctl policy subject-condition-sets create \
    --subject-set '[".clientId == \"<your-client-id>\""]' \
    --label "My Service Account"

Two problems:

  1. Flag is --subject-sets (plural), not --subject-set. See otdfctl/docs/man/policy/subject-condition-sets/create.md.
  2. The value shape is wrong. The flag takes a structured JSON array of subject sets — not a JQ-style expression string. The platform parses each subject set with protojson.Unmarshal into a policy.SubjectSet. The shown form ('[".clientId == \"...\""]') cannot parse and otdfctl will error.

What the example should look like

Following the structure documented in the same repo's Subject Mapping Guide and verified against otdfctl/cmd/policy/subjectConditionSets.go:

otdfctl policy subject-condition-sets create \
  --subject-sets '[
    {
      "condition_groups": [{
        "boolean_operator": 1,
        "conditions": [{
          "subject_external_selector_value": ".clientId",
          "operator": 1,
          "subject_external_values": ["<your-client-id>"]
        }]
      }]
    }
  ]' \
  --label "My Service Account"

Impact

External developers following the SDK troubleshooting page to grant themselves entitlements will hit an otdfctl error on the first subject-condition-sets create step, with no obvious indication that the canonical guide is wrong. The Subject Mapping Guide on the same docs site has the correct syntax — fixing this snippet to point at or mirror that guide is the cleanest resolution.

Suggested fix

Replace the subject-condition-sets create block in docs/sdks/troubleshooting.mdx with the structured form above, or replace the entire mini-tutorial with a link to the Subject Mapping Guide (which already covers this flow correctly and in depth).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions