Skip to main content

Policy - AI, Templates, OpenAPI

Simplified Policy Creation​

policy create simple

A simple policy table creation wizard with the resources, actions and roles. You can provide resources, actions, and roles as arguments or enter them interactively.

Options​

  • api-key <string> Optional: The Permit API key of the environment.

  • resources <string[]> (Optional) : Array of resources in the format: "key:name@attribute1,attribute2"

    • key: Resource Key
    • name: Resource display Name
    • @attribute1,attribute2 : comma-seperated list of attributes.

  • actions <string[]> (Optional) : Array of actions in the format: "key:description@attribute1,attribute2"

    • key : Action Key
    • description : Action description
    • @attribute1,attribute2: Comma-sperated list of attributes.

  • roles <string[]> (Optional) : Array of roles in the format: "role|resource:action|resource:action" or "role|resource"

    • role: Role key
    • resource:action: The resource and the action to declare the permissions.

Example​

$ permit policy create simple \
  --api-key permit_key_abc123
  --resources users:Users@department,role --resources posts:Posts@category \
  --actions create:Create --actions read:Read \
  --roles admin|users:create|posts:read --roles editor|posts

Policy Creation with AI (LLM)​

policy create ai

This command allows you to create RBAC policies using natural language. It uses AI to convert your descriptions into structured Role-Based Access Control policies that can be applied to your Permit.io environment.

Options​

  • --api-key <string> (Optional) - Your Permit.io API key. If not provided, the command will use your stored credentials.

Example​

$ permit policy create ai
Type your prompt...
A CRM SaaS application with different user types

This will start an interactive chat where you can describe your authorization requirements in natural language. The AI will convert your description into a structured RBAC policy with resources, roles, and permissions.

For example, you could describe:

  • A CRM SaaS application with different user types
  • Baseline WordPress policy with extended self-service capabilities
  • A file storage system with varying levels of access
  • Internal ticket management system for production teams

The AI will generate appropriate resources, roles, and permissions based on your description. The generated policy will be displayed in a table format showing the resources, actions, roles, and permissions. You can then approve or reject the generated policy.

If you approve the policy, the CLI will apply the policy to your Permit.io environment, creating all the resources, roles, and permissions defined in the policy.

Interactive Policy Wizard​

Define resources, generate test users, and assign roles through a simple step-by-step flow.

permit init​

Initialize the Permit policy wizard, which takes you through all the steps from configuring a policy to enforcing it in the application.

Arguments (Optional):

  • --api-key <string>: Use an environment API Key to create and store the policy.

Example:

$ permit init --api-key permit_key

Template-Based Policy Setup​

Use pre-built policy templates to automate rule creation for different industries.

permit env template list​

List all the available policy templates to apply to your environment.

Arguments (Optional)

  • --api-key <string> - API Key to be used for the environment to apply the Terraform template

Example:

$ permit env template list

permit env template apply​

Applies a policy template to your current environment, which is useful for quickly setting up new environments with predefined configurations.

Note: The command uses the Terraform provider to apply the template, but a Terraform installation is not required.

Arguments (Optional)

  • --api-key <string> - API Key to be used for the environment to apply the policy template
  • --local - to run the Terraform command locally (instead of on the server - will fail if Terraform isn’t installed)
  • --template <string> - skips the template choice and applies the given template. Will fail if the template doesn’t exist.

Example:

$ permit env template apply --template mesa-verde-banking-dem

Policy from OpenAPI​

env apply openapi

This command creates a full policy schema in Permit by reading an OpenAPI spec file and using -x-permit extensions to define resources, actions, roles, relations, and more. This enables developers to use their OpenAPI schema as a configuration source for their authorization policy.

Options​

  • --api-key <string> (Optional) - API key for Permit authentication
  • --spec-file <string> (Optional) - Path to the OpenAPI file to read from. It could be a local path or an HTTP endpoint.

Example​

# Run with spec file locally:
$ permit env apply openapi --spec-file ./api-spec.json

# Run With API key:
$ permit env apply openapi --key permit_key_... --spec-file https://raw.githubusercontent.com/daveads/openapispec/main/blog-api.json

OpenAPI Extensions​

The command uses the following -x-permit extensions in your OpenAPI spec to map elements to the Permit policy:

Path or Endpoint Level Extensions​

  • x-permit-resource - The resource name to map the path to. This field is REQUIRED for a path to be mapped.

Operation Level Extensions (HTTP Method Level)​

  • x-permit-action - Name of an action to map the HTTP method to. If not provided, the HTTP method name (get, post, etc.) will be used as the action.
  • x-permit-role - Name of a top-level role that is ALLOWED for this particular operation.
  • x-permit-resource-role - Name of a resource-level role that is ALLOWED for this particular operation.
  • x-permit-relation - A JSON object defining a relation between resources.
  • x-permit-derived-role - A JSON object defining role derivation rules.

Example OpenAPI Spec with Permit Extensions​

openapi: 3.0.3
info:
  title: 'Blog API with Permit Extensions'
  version: '1.0.0'
paths:
  /posts:
    x-permit-resource: blog_post
    get:
      summary: List all posts
      x-permit-action: list
      x-permit-role: viewer
      # ...
    post:
      summary: Create a new post
      x-permit-action: create
      x-permit-role: editor
      x-permit-resource-role: post_creator
      # ...
  /posts/{postId}:
    x-permit-resource: blog_post
    get:
      summary: Get a post by ID
      x-permit-action: read
      x-permit-role: viewer
      # ...
    put:
      summary: Update a post
      x-permit-action: update
      x-permit-role: editor
      # ...
    delete:
      summary: Delete a post
      x-permit-action: delete
      x-permit-role: admin
      # ...
  /posts/{postId}/comments:
    x-permit-resource: blog_comment
    get:
      summary: Get comments for a post
      x-permit-action: list
      x-permit-role: viewer
      x-permit-relation:
        subject_resource: blog_comment
        object_resource: blog_post
        key: belongs_to_post
        name: Belongs To Post
      # ...
    post:
      summary: Add a comment to a post
      x-permit-action: create
      x-permit-role: commenter
      x-permit-derived-role:
        key: post_commenter
        name: Post Commenter
        base_role: viewer
        derived_role: commenter
      # ...

Check this repo for a good example

Complex Extension Objects​

For the more complex extensions that accept objects instead of strings, here's the expected structure:

x-permit-relation Object Structure​

{
	"subject_resource": "string", // Required: The source resource in the relation
	"object_resource": "string", // Required: The target resource in the relation
	"key": "string", // Optional: Unique identifier for the relation (generated if not provided)
	"name": "string" // Optional: Human-readable name (generated if not provided)
}

x-permit-derived-role Object Structure​

{
	"key": "string", // Optional: Unique identifier for the derived role
	"name": "string", // Optional: Human-readable name for the derived role
	"base_role": "string", // Required: The role that grants the derived role
	"derived_role": "string", // Required: The role to be derived
	"resource": "string" // Optional: The resource that the derived role applies to (defaults to the path's resource)
}

URL Mapping​

After creating the policy elements based on the -x-permit extensions, the command will automatically create URL mappings in Permit. These mappings connect API endpoints to the appropriate resources and actions for runtime authorization checks.

For each endpoint with the required extensions, a mapping rule will be created with:

  • URL path from the OpenAPI spec
  • HTTP method
  • Resource from x-permit-resource
  • Action from x-permit-action or the HTTP method

This enables Permit to perform authorization checks directly against your API endpoints.

OPA Policy​

permit opa policy

This command will print the available policies of an active OPA instance. This is useful when you want to see the policies in your OPA instance directly; without fetching them from the Permit server, or if you're not using Permit at all.

Arguments (Optional)​

  • --api-key <string> - the API key to authenticate the operation
  • --server-url <string> - the URL of the OPA server to fetch the policies from (default: http://localhost:8181)

Example​

$ permit opa policy --server-url http://localhost:8181 --api-key permit_key_..........

Contents