Skip to main content

API Commands

Simplifies the usage of Permit’s API, allowing you to perform most API actions directly through the CLI. This collection of commands provides direct access to Permit.io's API functionality.

Quick Examples​

List users in the default environment:

$ permit api users list

Assign a role to a user:

$ permit api users assign --user user@example.com --role admin --tenant default

Unassign a role from a user:

$ permit api users unassign --user user@example.com --role admin --tenant default

Permit API Commands reference​

permit api sync user​

This command will replace User / Sync User in Permit. If the user already exists, it will update the user with the new data. If the user does not exist, it will create a new user with the provided data.

Arguments (Optional):

  • --key <string> - a unique ID by which Permit will identify the user for permission checks. It has the alias user-id.
  • --email <string>- user email. If synced, it will be unique inside the environment.
  • --first_name <string> - user first name.
  • --last_name <string> - user last name.
  • --attributes <object> - user attributes used to enforce attribute-based access control policies.
  • --roles - user roles. Can be given in 3 different formats:
    1. The only role the default tenant is assigned.
    2. Both the role and the tenant
    3. The resource Instance along with the role.
  • --api-key <string>: a Permit API key to authenticate the operation. If not provided, the command will take the one you logged in with.

Example:

$ permit api sync user
  --userid "892179821739812389327" \\
  --email "jane@coolcompany.com" \\
  --firstName "Jane" \\
  --lastName "Doe" \\
  --attributes  "age:30" \\
  --attributes "location:NY" \\
  --roles "admin:stripe-inc" \\
  --roles "developer" \\
  --roles "project:123#developer"

permit api users list​

List all users in Permit.

Arguments (Optional):

  • --api-key <string> - your Permit API key
  • --project-id <string> - your Permit project ID
  • --env-id <string> - your Permit environment ID
  • --expand-key - show full key values instead of truncated (default: false)
  • --page <number> - page number for pagination (default: 1)
  • --per-page <number> - number of items per page (default: 50)
  • --role <string> - filter users by role
  • --tenant <string> - filter users by tenant
  • --all - fetch all pages of users (default: false)

Example:

$ permit api users list
	--tenant default
	--role admin
	--all

In the example above, we fetch a list of all users with the admin role in the default tenant.

permit api users assign​

Assign a user to a specific role in Permit.

Arguments (Required):

  • --user <string> - user ID to assign role to
  • --role <string> - role key to assign
  • --tenant <string> - tenant key for the role assignment

Arguments (Optional):

  • --api-key <string> - your Permit API key
  • --project-id <string> - Permit project ID
  • --env-id <string> - Permit environment ID

Example:

$ permit api users assign --user user@example.com --role admin --tenant default

permit api users unassign​

Remove a role assignment from a user in Permit.

Arguments (Required):

  • --user <string> - user ID to unassign the role from
  • --role <string> - role key to unassign
  • --tenant <string> - tenant key for the role unassignment

Arguments (Optional):

  • --api-key <string> - your Permit API key
  • --project-id <string> - Permit project ID
  • --env-id <string> - Permit environment ID

Example:

$ permit api users unassign --user user@example.com --role admin --tenant default

permit api create proxy​

Create a new proxy config inside the Permit.io system.

Arguments (Optional):

  • --api-Key <string> - your Permit API key.
  • --secret <string>- Proxy config secret is set to enable the Permit Proxy to make proxied requests to the backend service.
  • --key <string> - a unique ID by which Permit will identify the user for permission checks..
  • --name <string> - The name of the proxy config, for example(e.g., Stripe API).
  • --auth-mechanism <string> - Authentication mechanism used to inject the secret. One of: Bearer, Basic, Headers. Defaults to Bearer.
  • --mapping-rules - Mapping rule must start with a valid HTTP method, then a URL, then a resource (e.g. "get|https://api.example.com|users"), then optionally: "|action|priority|{headers}|url_type".

Mapping rules can also be provided as individual Arguments (Optional - (Ignored if the mapping-rule arguments are present):

  • --mapping-rule-method <string> - Must be a valid HTTP method (get|put|post|delete|options|head|patch).
  • --mapping-rule-url <string> - Must be a valid URL (e.g. https://api.example.com).
  • --mapping-rule-resource <string> - Resource to match against the request (no leading slash).
  • --mapping-rule-action <string> - Optional action name for the mapping rule.
  • --mapping-rule-headers <array> - Optional list of headers, each as "Key:Value".
  • --mapping-rule-priority <integer> - Optional priority (positive integer) for the mapping rule.
  • --mapping-rule-url-type <string> - How to interpret the URL: "regex" or "none".

Examples:

$ permit api create proxy
  --api-key "YOUR_API_KEY" \\
  --secret "YOUR_SECRET" \\
  --key "KEY" \\
  --name "jhon" \\
  --auth-mechanism  "Bearer" \\
  --mapping-rules "get|https://api.example.com|users|getUsers|10|{Authorization:Bearer abc,X-Custom:v7}|regex"

Individual mapping rules:

$ permit api create proxy
  --api-key "YOUR_API_KEY" \\
  --secret "YOUR_SECRET" \\
  --key "KEY" \\
  --name "jhon" \\
  --auth-mechanism  "Bearer" \\
  --mapping-rule-url https://foo.com \\
  --mapping-rule-method post \\
  --mapping-rule-resource myresource \\
  --mapping-rule-headers "k1:v1" \\
  --mapping-rule-action create \\
  --mapping-rule-priority 10 \\
  --mapping-rule-url-type regex

permit api list proxy​

List all the proxy configs defined within an environment.

Arguments (Optional):

  • --api-key <string> - your Permit API key
  • --expand-key - show full key values instead of truncated (default: false)
  • --page <number> - page number for pagination (default: 1)
  • --per-page <number> - number of items per page (default: 30)
  • --all - fetch all pages of users (default: false)

Example:

$ permit api list proxy
        --api-key "YOUR_API_KEY" \\
        --expand-key
	--page 2
	--per-page 50
	--all

In the example above, we fetch a list of all proxies in the default environment.

Contents