diff --git a/docs/docs/guides/integrate/pat.md b/docs/docs/guides/integrate/pat.md new file mode 100644 index 0000000000..102209fb49 --- /dev/null +++ b/docs/docs/guides/integrate/pat.md @@ -0,0 +1,45 @@ +--- +title: PAT (Personal Access Token) +--- + + +A Personal Access Token (PAT) is a ready to use token which can be used as _Authorization_ header. +At the moment ZITADEL only allows PATs for machine accounts (service users). + +It is an alternative to the JWT profile authentication where the service user has a key to authenticate. Read more about that [here](serviceusers) + +## Create a Service User with a PAT + + +1. Navigate to Service Users +2. Click on **New** +3. Enter a user name and a display name +4. Click on the Personal Access Token menu point in the detail of your user +5. Click on **New** +6. You can either set an expiration date or leave it empty if you don't want it to expire +7. Copy the token from the dialog (You will not see this again) + +![Create new service user](/img/guides/console-service-user-pat.gif) + +## Grant role for ZITADEL + +To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL. + +1. Go to the detail page of your organization +2. Click in the top right corner the "+" button +3. Search for your service user +4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](../manage/console/managers)) + +![Add org owner to service user](/img/guides/console-service-user-org-owner.gif) + + +## Call ZITADEL API with PAT + +Because the PAT is a ready to use Token, you can add it as Authorization Header and send it in your requests to the ZITADEL API. +In this example we read the organization of the service user. + +```bash +curl --request GET \ + --url {your-domain}/management/v1/orgs/me \ + --header 'Authorization: Bearer {PAT}' +``` \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index bbd2521b3e..d733751cb1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -133,6 +133,7 @@ module.exports = { items: [ "guides/integrate/serviceusers", "guides/integrate/access-zitadel-apis", + "guides/integrate/pat", "guides/integrate/access-zitadel-system-api", "guides/integrate/export-and-import", ], diff --git a/docs/static/img/guides/console-service-user-org-owner.gif b/docs/static/img/guides/console-service-user-org-owner.gif new file mode 100644 index 0000000000..fc44516b9f Binary files /dev/null and b/docs/static/img/guides/console-service-user-org-owner.gif differ diff --git a/docs/static/img/guides/console-service-user-pat.gif b/docs/static/img/guides/console-service-user-pat.gif new file mode 100644 index 0000000000..932759aa87 Binary files /dev/null and b/docs/static/img/guides/console-service-user-pat.gif differ