API commands in the Permit CLI

Call the Permit API from your terminal with the permit api commands: sync users, list users, assign and remove roles, and manage Permit Proxy configurations. This reference is for developers who manage users and roles from scripts or CI/CD pipelines, or who test a policy with real users.

Before you use these commands, install the Permit CLI and sign in with permit login. See Install and use the Permit CLI. Each command also accepts --api-key instead of the stored credentials, and runs against the environment of your credentials or API key.

Common tasks

List the users in your environment:

$ permit api users list

Assign the admin role in the default tenant to a user:

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

Remove the admin role in the default tenant from a user:

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

To confirm a role change, run permit api users list --role admin --tenant default. The list includes the user after an assignment, and doesn't include the user after an unassignment.

User commands

permit api sync user

permit api sync user creates a user, or updates the user when the key exists, with attributes and role assignments. The command calls the Permit API's replace user operation, so the values you pass replace the user's stored values. For when to sync users, see Sync users.

Flag	Description
--key <string>	The user key that permission checks use. Alias: -userId.
--email <string>	The user's email address.
--first-name <string>	The user's first name.
--last-name <string>	The user's last name.
--attributes <string...>	A user attribute in the key:value form, used by attribute-based access control (ABAC) policies. Repeat the flag for each attribute.
--roles <string...>	A role assignment. Repeat the flag for each assignment. See the formats below.
--api-key <string>	The environment API key.

--roles accepts four formats:

Format	Example	Assigns
role	developer	The role in the default tenant.
tenant/role	stripe-inc/admin	The role in the tenant.
resource_type:instance#role	project:123#developer	The resource role on the resource instance.
tenant/resource_type:instance#role	stripe-inc/project:123#developer	The resource role on the resource instance in the tenant.

$ permit api sync user \
  --key "892179821739812389327" \
  --email "jane@example.com" \
  --first-name "Jane" \
  --last-name "Doe" \
  --attributes "age:30" \
  --attributes "location:NY" \
  --roles "stripe-inc/admin" \
  --roles "developer" \
  --roles "project:123#developer"

To confirm, open the user in the Directory screen of the Permit dashboard, and check the attributes and roles.

permit api users list

permit api users list lists the users of an environment with their roles.

Flag	Alias	Default	Description
--role <string>	-r	All roles	Lists only users with this role key.
--tenant <string>	-t	All tenants	Lists only users in this tenant key.
--page <number>	-p	1	The page of results.
--per-page <number>	-l	50	The number of users on a page.
--all	-a	false	Fetches every page.
--expand-key	-e	false	Shows full keys instead of truncated keys.
--project-id <string>		Credentials	The project ID.
--env-id <string>		Credentials	The environment ID.
--api-key <string>		Stored credentials	The environment API key.

List every user with the admin role in the default tenant:

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

permit api users assign

permit api users assign assigns a role to a user in a tenant.

Flag	Required	Description
--user <string>	Yes	The user key.
--role <string>	Yes	The role key to assign.
--tenant <string>	Yes	The tenant key of the role assignment.
--project-id <string>	No	The project ID. Defaults to the project of your credentials.
--env-id <string>	No	The environment ID. Defaults to the environment of your credentials.
--api-key <string>	No	The environment API key.

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

permit api users unassign

permit api users unassign removes a role assignment from a user in a tenant.

Flag	Required	Description
--user <string>	Yes	The user key.
--role <string>	Yes	The role key to remove.
--tenant <string>	Yes	The tenant key of the role assignment.
--project-id <string>	No	The project ID. Defaults to the project of your credentials.
--env-id <string>	No	The environment ID. Defaults to the environment of your credentials.
--api-key <string>	No	The environment API key.

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

Permit Proxy commands

A proxy configuration tells the Permit Proxy how to forward requests to your HTTP API: the secret to inject, and mapping rules that match each request's method and URL to a resource and an action. For how Permit checks requests by URL, see URL mapping checks.

permit api create proxy

permit api create proxy creates a proxy configuration in your environment.

Flag	Description
--key <string>	A unique key for the proxy configuration. Letters, digits, -, and _ only.
--name <string>	The display name of the proxy configuration, for example Stripe API.
--secret <string>	The secret that the Permit Proxy uses to authenticate with your HTTP API.
--auth-mechanism <Bearer | Basic | Headers>	How the Permit Proxy injects the secret. Defaults to Bearer. Case-sensitive.
--mapping-rules <string...>	A mapping rule in the method|url|resource|action|priority|{Key:Value,...}|url_type form. method, url, and resource are required. Repeat the flag for each rule.
--api-key <string>	The environment API key.

To define a single mapping rule with separate flags instead, use the flags below. The command ignores them when you pass --mapping-rules.

Flag	Description
--mapping-rule-method <string>	The HTTP method: get, put, post, delete, options, head, or patch.
--mapping-rule-url <string>	The target URL, for example https://api.example.com.
--mapping-rule-resource <string>	The resource key, without a leading slash.
--mapping-rule-action <string>	The action key. Optional.
--mapping-rule-priority <number>	A positive integer priority. Optional.
--mapping-rule-headers <string...>	A header in the Key:Value form. Optional. Repeat the flag for each header.
--mapping-rule-url-type <regex | none>	How to match the URL: as a regular expression, or as a plain URL. Optional.

Create a proxy configuration with one mapping rule in a single --mapping-rules value:

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

Create a proxy configuration with one mapping rule in separate flags:

$ permit api create proxy \
  --api-key "YOUR_API_KEY" \
  --secret "YOUR_SECRET" \
  --key "KEY" \
  --name "Example API" \
  --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

To confirm, run permit api list proxy. The list includes the key of the new proxy configuration.

permit api list proxy

permit api list proxy lists the proxy configurations of an environment.

Flag	Alias	Default	Description
--page <number>	-p	1	The page of results.
--per-page <number>	-l	30	The number of proxy configurations on a page.
--all	-a	false	Fetches every page.
--expand-key	-e	false	Shows full keys instead of truncated keys.
--api-key <string>		Stored credentials	The environment API key.

List every proxy configuration with full keys:

$ permit api list proxy --api-key "YOUR_API_KEY" --expand-key --all

Related pages

• Sync users
• URL mapping checks
• Check a permission with the Permit CLI
• Permit CLI command index