Policy API

Base URL: https://policy.opteryx.app

Overview

Workspace policy listing, inspection, creation, updates, and deletion for access-control management.

Endpoints

List workspace policies

Request: get/v1/access/workspace/{workspace}

Tags: Access Control

Get all access policies for a workspace. Requires owner or admin access.

Path Parameters

• workspace string [path; required] Workspace name

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json WorkspacePoliciesResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Export effective permissions

Request: get/v1/access/workspace/{workspace}/effective-permissions.csv

Tags: Access Control

Export a CSV of who has access to every dataset and view in the workspace, resolving each policy's pattern against the workspace's actual catalog. A policy scoped to a wildcard pattern appears on one row per dataset it covers, so the same policy_id can repeat across many rows. Owner-only: this is a full map of who can reach every resource in the workspace, not a single grant.

Path Parameters

• workspace string [path; required] Workspace name

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — CSV export of effective permissions. (application/json object, text/csv string)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Bootstrap a new workspace's initial policies

Request: post/v1/access/workspace/{workspace}/genesis

Tags: Access Control

Create the initial set of access policies for a brand-new workspace, one policy per {identity, role} pair, each scoped to the whole workspace (pattern {workspace}.*). This is a trusted bootstrap operation for whatever creates the workspace record in the first place (e.g. billing.opteryx's workspace-create endpoint) to hand it an explicit member list at creation time, rather than every caller becoming sole owner. Refuses with 409 if the workspace already has any policy at all -- this can only be used once, to bootstrap a workspace that doesn't have policies yet, not to add owners to one that already does.

Path Parameters

• workspace string [path; required] Workspace name

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: GenesisGrantRequest
  • grants array<GenesisGrant> [required] Identity/role pairs to grant over the whole workspace

Responses

• 201 — Successful Response (application/json GenesisGrantResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Create policy

Request: post/v1/access/workspace/{workspace}/policies

Tags: Access Control

Create a new access policy for a user in the workspace.

Path Parameters

• workspace string [path; required] Workspace name

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: CreatePolicyRequest
  • principal Principal [required] User to grant access to
  • role string [required] Role to grant. See Security & Permissions for what each role can do. Allowed values: owner, admin, writer, reader
  • pattern string [required] Resource pattern (e.g., 'analytics.*')

Responses

• 201 — Successful Response (application/json CreatePolicyResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Get policy details

Request: get/v1/access/workspace/{workspace}/policies/{policy_id}

Tags: Access Control

Get detailed information about a specific policy.

Path Parameters

• workspace string [path; required] Workspace name
• policy_id string [path; required] Policy ID

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json PolicyDetail)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Update policy

Request: put/v1/access/workspace/{workspace}/policies/{policy_id}

Tags: Access Control

Update an existing access policy.

Path Parameters

• workspace string [path; required] Workspace name
• policy_id string [path; required] Policy ID

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: UpdatePolicyRequest
  • role string [required] Updated role. See Security & Permissions for what each role can do. Allowed values: owner, admin, writer, reader
  • pattern string [required] Updated resource pattern

Responses

• 200 — Successful Response (application/json object)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Delete policy

Request: delete/v1/access/workspace/{workspace}/policies/{policy_id}

Tags: Access Control

Remove an access policy from the workspace.

Path Parameters

• workspace string [path; required] Workspace name
• policy_id string [path; required] Policy ID

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json object)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live