Merge pull request #233 from permitio/filip/per-8867-add-api-logs-inf…

…ormation-to-the-docs

Filip/per 8867 add api logs information to the docs

docs/api/api-with-cli.mdx

@@ -3,7 +3,10 @@ sidebar_position: 3
 title: Calling the API
 ---
 
-# Use API
+import apiLogs from "/ui-videos/api/api-logs.mp4";
+import apiLogEvent from "/ui-videos/api/api-log-event.mp4";
+
+# Using the API
 
 You can manage most of Permit's functionality from the [web application](https://app.permit.io/).
 
@@ -16,6 +19,11 @@ This can be achieved with Postman or any other REST client as well as with CLI t
 In order to call the API, you will need to get the API key from the Permit Dashboard.
 Go to the [Settings -> API Keys](https://app.permit.io/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](/img/api_keys/api_keys.png)
 
 You can either reveal and copy an existing API key or create a new key by clicking on **Create Key**.
@@ -28,6 +36,39 @@ You can either reveal and copy an existing API key or create a new key by clicki
 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.
 
+## 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.
+
+<video controls>
+  <source src={apiLogs} />
+</video>
+
+2. 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.
+
+3. To review a specific call, click on it, and it will display an `API Log Event`.
+
+<video controls>
+  <source src={apiLogEvent} />
+</video>
+
+4. The `API Log Event` includes additional information about the call, including `Request` and `Response` tabs.
+
+5. 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](https://api.permit.io/v2/redoc)