query-orchestration/cmd/auth_related/permit.setup

Permit.io Setup Tool

This CLI tool configures Permit.io roles and resources based on a YAML configuration file.

Prerequisites

• Go 1.24+
• Permit.io API key with permissions to create resources and roles
• Project ID and Environment ID from your Permit.io account

Installation

The tool requires the gopkg.in/yaml.v3 package:

go get gopkg.in/yaml.v3

Usage

Basic Usage

Get the permit api key from permit.io login with the aarete account and retrieve the key for the environment you want to work with. Note that each environment has its own api key.

Note that when you create a brand new environment in permit.io it creates dummy admin, viewer and editor roles. These must be deleted before you run the tool since they conflict with some of the names we use for our roles.

export PERMIT_API_KEY="permit_key_omitted-here"
go run setup_permit.go -list
go run setup_permit.go -config permit_policies.yaml -project default -env <id of the env>

Note: When you do the list operation you will get the id of the target environment to put in the -env parameter.

Environments in permit

You must create a new enviroment in permit.io manually at this time. This tools just sets up the resources and policies for an existing enviromment. We will have to extend this tool later to create the environment if it does not already exist once we are creating a lot of enviroments.

Dry Run Mode

To see what would be created without making actual changes:

go run setup_permit.go -config permit_policies.yaml -project doczy -env Development -dry-run

Command-Line Options

• -config <file>: Path to YAML configuration file (default: permit_policies.yaml)
• -project <id>: Permit.io project ID or key (required)
• -env <id>: Permit.io environment ID or key (required)
• -dry-run: Print planned changes without applying them

Environment Variables

• PERMIT_API_KEY: Your Permit.io API key (required)

Configuration File Format

The YAML configuration file defines resources and roles:

resources:
  - name: admin
    description: Administrative functions
    actions:
      - get
      - post
      - patch
      - delete
      - head

roles:
  - name: super_admin
    description: Full system access
    permissions:
      admin:
        - get
        - post
        - patch
        - delete
        - head
      client:
        - get
        - post

What It Does

The tool performs the following steps:

1. Creates Resources: Creates each resource defined in the YAML file with its associated actions
2. Creates Roles: Creates each role with its permission assignments

The tool is idempotent - if a resource or role already exists, it will update it with the current definition.

Important: The tool only adds or updates resources and roles. It never deletes anything from Permit.io. This means:

• If you remove a resource or role from the YAML file, it will remain in Permit.io
• If you rename a resource or role in the YAML, the old name will remain in Permit.io and a new one will be created
• To remove resources or roles, you must do so manually through the Permit.io dashboard or API

Example Output

Setting up Permit.io configuration for project=doczy, env=Development
Dry run: false

=======================================================================
STEP 1: Creating Resources and Actions
=======================================================================

Creating resource: admin
  Description: Administrative functions (user management)
  Actions: [get post patch delete head]
  ✓ Resource created successfully

Creating resource: client
  Description: Client management
  Actions: [get post patch delete]
  ✓ Resource created successfully

=======================================================================
STEP 2: Creating Roles with Permissions
=======================================================================

Creating role: super_admin
  Description: Full system access for platform administrators
  Permissions: [admin:get admin:post admin:patch admin:delete admin:head client:get ...]
  ✓ Role created successfully

Creating role: user_admin
  Description: User management - primarily for creating new client users
  Permissions: [admin:get admin:post admin:patch admin:delete admin:head home:get]
  ✓ Role created successfully

=======================================================================
Setup Complete!
=======================================================================

Error Handling

• If a resource or role already exists, the tool will skip it and continue
• If an error occurs creating a resource or role, the error is logged but the tool continues with remaining items
• All API errors include the HTTP status code and response body for debugging

Finding Your Project and Environment IDs

You can find your project and environment IDs in the Permit.io dashboard:

1. Go to Settings > API Keys
2. Your environment key is typically shown in the API key details
3. The project ID can be found in the URL when viewing your project
4. Alternatively, you can use the project/environment "key" instead of the numeric ID

Troubleshooting

"PERMIT_API_KEY environment variable must be set"

Set the environment variable before running:

export PERMIT_API_KEY="your-api-key-here"

"API error (status 404)"

• Verify your project and environment IDs are correct
• Ensure your API key has access to the specified project/environment

"API error (status 401)"

• Check that your API key is valid
• Ensure the API key has the necessary permissions

"API error (status 409): Resource already exists"

This is normal - the tool will skip existing resources and continue

Notes

• The tool uses the Permit.io REST API directly (not the Go SDK)
• All changes are made immediately - use -dry-run to preview first
• Resources must be created before roles that reference them
• The tool follows the same API patterns used in the user.creation.tool