Skip to main content
Version: 2.0.0

Using the API

You can manage most of Permit's functionality from the web application.

That being said, you may want to use the API from time to time.

This can be achieved with Postman or any other REST client as well as with CLI tools like curl.

Rate Limiting​

Permit's API is rate-limited to prevent abuse.

The number of requests you can make is limited to 5,000 overall requests per minute. For fact requests (/v2/facts/*), the limit is 3,000 requests per minute. For schema requests (/v2/schema/*), the limit is 1,000 requests per minute. For bulk requests, the limit is 100 requests per 10 minutes.

The rate limit is adjustable per customer, reach out to us if you need to adjust the rate limit.

API Endpoints and Regions​

All the examples in this documentation are using the api.permit.io endpoint.

But if you are using EU region (available at Permit Pro), you need to replace api.permit.io with the region-specific endpoint.

For EU region, the endpoint is api.eu.permit.io.

Permit init example on Node SDK​

const permit = new Permit({
  // the API key to the Permit environment you wish to connect to
  token: "<YOUR_API_KEY>",
  // the url in which the SDK can connect to the PDP container
  pdp: "http://localhost:7766",
  // use this to turn on sdk logs
  log: {
    level: "debug",
  },
  // the region in which the Permit environment is located
  apiUrl: "https://api.eu.permit.io",
});

Get your API Key​

In order to call the API, you will need to get the API key from the Permit Dashboard. Go to the Settings -> API Keys screen.

note

If you are using the API to create new organizations, or manage higher-level actions that are not environment specific, you will need to generate an organization key.

Get API Key

You can either reveal and copy an existing API key or create a new key by clicking on Create Key.

Create API Key

There are 3 types of API Keys:​

  1. Organization API Keys can act on your entire Permit Organization (i.e: workspace) and access all projects and environment within that workspace.
  2. Project API Keys can access a single project and all the environments that belong to that project.
  3. Environment API Keys can access a single environment. Only this type of API key can be used by the PDP container.
note

Read more about API Key levels.

Working with the API Logs​

Permit's entire no-code dashboard is API-driven. This means that everything you do in the UI, can also be done via the API. Each API call consists of a request and a response. In Permit, every external API call is recorded in the logs, which are accessible via the Permit UI.

note

API logs are Organization specific.

To review these logs:

  1. Go to the API Log tab under Settings. This screen will display every API call made within the current organization.

  1. The API Log screen consists of a Timestamp of when the API call was performed, the Actor who performed the call, the Action (The endpoint that was called), and the Response returned.

  2. To review a specific call, click on it, and it will display an API Log Event.

  1. The API Log Event includes additional information about the call, including Request and Response tabs.

  2. The Request tab includes the payload sent to the API endpoint, and the Response tab includes all the data received back from the endpoint.

tip

The Response tab is a great tool to debug why your API calls might be failing, as it gives you insight into what's happening, providing you with valuable error messages that can be used to understand what's wrong.

API Docs​

The API docs are available at https://api.permit.io/v2/redoc

Using Postman​

You can download Postman and use it to experiment with the API.

You need to provide the API Key you got from permit in the Authorization header.

Select bearer token in the authentication type and paste your API Key there.

Use Postman

Using CURL​

You can use the curl command line tool to use or test the API.

You need to provide the API Key you got from permit in the Authorization header.

Get all users​

Run it with the following command to get all the users in your organization:

curl -H "Authorization: Bearer <API Key>" https://api.permit.io/v2/facts/{projectKey}/{environmentKey}/users

Get all tenants​

Use this command to get all your tenants:

curl -H "Authorization: Bearer <API Key>" https://api.permit.io/v2/facts/{projectKey}/{environmentKey}/tenants

Contents