Add PAT documentation

.vitepress/sidebars/dashboard/concepts.ts

@@ -8,6 +8,10 @@ export const conceptsSidebar: DefaultTheme.SidebarItem[] = [
         text: "Introduction",
         link: "/dashboard/concepts/",
       },
+      {
+        text: "Personal Access Token",
+        link: "/dashboard/concepts/pat",
+      },
       {
         text: "Workspace",
         link: "/dashboard/concepts/workspace",

.vitepress/sidebars/dashboard/guides.ts

@@ -10,6 +10,15 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [
       },
     ],
   },
+  {
+    text: "Users",
+    items: [
+      {
+        text: "Creating a Personal Access Token",
+        link: "/dashboard/guides/create_pat",
+      },
+    ],
+  },
   {
     text: "Teams",
     items: [

src/app/concepts/instance_authentication.md

@@ -12,10 +12,15 @@ Authentication in Caido is based on [OAuth 2.0](https://www.rfc-editor.org/rfc/r
 
 Like we mentioned in [instance registration](./instance_registration.md), each Caido instance registers itself with our Cloud as an `OAuth 2.0 client`.
 
-When you click on `Login` on the instance, it performs a <a href="https://www.rfc-editor.org/rfc/rfc8628.html" target="_blank">Device Authorization</a> flow. Currently this flow requires a human approval via the website (we are working on removing this limitation).
+When you click on `Login` on the instance, it performs a <a href="https://www.rfc-editor.org/rfc/rfc8628.html" target="_blank">Device Authorization</a> flow.
 
 <img alt="Authenticate user flow." src="/_images/authentication_user.png" width=800px center no-shadow/>
 
+This flow is usually approved with the consent form on the [Dashboard](https://dashboard.caido.io).
+It can also be approved using [Personal Access Tokens](/dashboard/concepts/pat) if you want to interact with the instance in headless mode (CICD for example).
+
+<img alt="Consent form for authentication" src="/_images/authentication_consent.png" width=400px center no-shadow/>
+
 ::: warning NOTE
 We do not make any guarantees on the lifetime of the tokens.
 Currently the access token is valid for 7 days and the refresh token is valid for 3 months.

src/dashboard/concepts/pat.md

@@ -0,0 +1,22 @@
+# Personal Access Token
+
+Personal Access Tokens (PAT) are used to access the public [API of Caido Cloud](https://developer.caido.io/reference/api.html).
+For example, they can be used to invite new members to a Team or approve an headless login to a Caido instance.
+
+You can easily recognize a Caido PAT as they start with `caido_`.
+
+::: info
+Each PAT is tied to a user and will act with the same level of permissions as that user.
+:::
+
+<img alt="Pat view for users" src="/_images/pat_user.png" width=900px center />
+
+A PAT can either be created to access resources for your own account or a specific Team (the resource owner).
+
+::: info
+PATs created for a Team will be visible by the admins of that Team, but they won't be able to revoke them.
+:::
+
+<img alt="Pat view for team admins" src="/_images/pat_team.png" width=900px center />
+
+To get started with PAT, [learn how to create one](/dashboard/guides/create_pat).

src/dashboard/guides/create_pat.md

@@ -0,0 +1,22 @@
+# Creating a Personal Access Token
+
+[PAT](/dashboard/concepts/pat) can be used as the authentication method for the [Caido Cloud API](https://developer.caido.io/reference/api.html).
+
+To create a new PAT, visit the <code><Icon icon="fas fa-key" /> Developer</code> page on your account.
+
+<img alt="PAT Page for user" src="/_images/pat_page.png" width=900px center />
+
+You can then click on `+ Create Token`. You will be presented with a form.
+
+The options are:
+
+- `Name`: A descriptive name for the  PAT
+- `Resource Owner`: Either Yourself or one of the Teams you belong to.
+- `Expiration`: When will the PAT expire, we strongly recommend setting an expiration date
+
+::: tip
+If you want to access resources (instances, users, subscription, etc.) for a Team, you need to select that Team as the resource owner.
+On the contrary, if you want to access resources for your own account, choose `Yourself` as the owner.
+:::
+
+<img alt="New PAT Form" src="/_images/new_pat.png" width=600px center />