Document ZenML Pro Personal Access Tokens and deprecate API tokens

.gitbook.yaml

@@ -236,7 +236,7 @@ redirects:
   how-to/manage-zenml-server/connecting-to-zenml: how-to/manage-zenml-server/connecting-to-zenml/README.md
   how-to/manage-zenml-server/connecting-to-zenml/connect-in-with-your-user-interactive: how-to/manage-zenml-server/connecting-to-zenml/connect-in-with-your-user-interactive.md
   how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account: how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account.md
-  how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token: how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token.md
+  how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token: how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account.md
   how-to/manage-zenml-server/mcp-chat-with-server: reference/llms-txt.md
   how-to/manage-zenml-server/migration-guide: how-to/manage-zenml-server/migration-guide/migration-guide.md
   how-to/manage-zenml-server/migration-guide/migration-zero-forty: how-to/manage-zenml-server/migration-guide/migration-zero-forty.md
@@ -296,4 +296,4 @@ redirects:
   # how-to/pipeline-development/training-with-gpus/accelerate-distributed-training: how-to/containerization/containerization.md
   how-to/pipeline-development/build-pipelines/name-your-pipeline-runs: how-to/steps-pipelines/steps_and_pipelines.md
   how-to/artifacts/complex_use_cases: how-to/artifacts/materializers.md
-  # how-to/notebooks: how-to/steps-pipelines/steps_and_pipelines.md
+  # how-to/notebooks: how-to/steps-pipelines/steps_and_pipelines.md

docs/book/api-docs/oss-api/oss-api/getting-started.md

@@ -32,48 +32,9 @@ If you are using the ZenML OSS server API using the methods displayed above, it
 Choosing a method:
 
 - Humans at the CLI: use [interactive login](https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-in-with-your-user-interactive).
-- Short‑lived scripts: use [temporary API tokens](https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token).
 - CI/CD and automation: use [service accounts + API keys](https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account).
 {% endhint %}
 
-### Using a short-lived API token
-
-You can generate a short-lived API token using the CLI or the ZenML UI. This is useful when you need a fast way to make authenticated HTTP requests to the ZenML API endpoints and you don't need a long-term solution.
-
-1. Generate a short-lived API token through the API Tokens page under your ZenML UI server settings, or the `zenml token` CLI command, as documented in the [Using an API token](../../../how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token.md) guide.
-
-2. Use the API token as the bearer token in your HTTP requests. For example, you can use the following command to check your current user:
-   *   using `curl`:
-
-       ```bash
-       curl -H "Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
-       ```
-   *   using `wget`:
-
-       ```bash
-       wget -qO- --header="Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
-       ```
-   *   using Python:
-
-       ```python
-       import requests
-
-       response = requests.get(
-         "https://your-zenml-server/api/v1/current-user",
-         headers={"Authorization": f"Bearer YOUR_API_TOKEN"}
-       )
-       print(response.json())
-       ```
-
-{% hint style="info" %}
-**Important Notes**
-
-* API tokens expire after the configured expiration time (default 1 hour) and need to be renewed periodically.
-* individual API tokens cannot be revoked after they are generated. If a token is compromised, you may need to lock the user account or service account to prevent further access.
-* Tokens are scoped to the user account or service account that was used to generate them and inherit their permissions.
-* For long-term programmatic access, it is instead recommended to [set up a service account API key](./#using-a-service-account-and-an-api-key).
-{% endhint %}
-
 ### Using a service account and an API key
 
 You can use a service account's API key to authenticate to the ZenML server's REST API programmatically. This is particularly useful when you need a long-term, secure way to make authenticated HTTP requests to the ZenML API endpoints.
@@ -122,9 +83,9 @@ Use the API key directly to authenticate your API requests by including it in th
 
 {% tab title="Token exchange authentication" %}
 
-Reduce the risk of API key exposure by periodically exchanging the API key for a short-lived API access token.
+Reduce the risk of API key exposure by periodically exchanging the API key for a short-lived API token.
 
-1. To obtain an API access token using your API key, send a POST request to the `/api/v1/login` endpoint. Here are examples using common HTTP clients:
+1. To obtain a short-lived API token using your API key, send a POST request to the `/api/v1/login` endpoint. Here are examples using common HTTP clients:
    *   using curl:
 
        ```bash
@@ -152,7 +113,7 @@ Reduce the risk of API key exposure by periodically exchanging the API key for a
        print(response.json())
        ```
 
-This will return a response like this (the API token is the `access_token` field):
+This will return a response like this (the short-lived API token is the `access_token` field):
 
 ```json
 {
@@ -164,7 +125,7 @@ This will return a response like this (the API token is the `access_token` field
 }
 ```
 
-2. Once you have obtained an API token, you can use it to authenticate your API requests by including it in the `Authorization` header. When the token expires, simply repeat the steps above to obtain a new token. For example, you can use the following command to check your current user:
+2. Once you have obtained a short-lived API token, you can use it to authenticate your API requests by including it in the `Authorization` header. When the short-lived API token expires, simply repeat the steps above to obtain a new one. For example, you can use the following command to check your current user:
    *   using curl:
 
        ```bash
@@ -194,9 +155,9 @@ This will return a response like this (the API token is the `access_token` field
 {% hint style="info" %}
 **Important notes**
 
-* API tokens are scoped to the service account that created them and inherit their permissions
+* Short-lived API tokens are scoped to the service account that created them and inherit their permissions
 * Tokens are temporary and will expire after a configured duration (typically 1 hour, but it depends on how the server is configured)
-* You can request a new token at any time using the same API key
-* For security reasons, you should handle API tokens carefully and never share them
+* You can request a new short-lived API token at any time using the same API key
+* For security reasons, you should handle short-lived API tokens carefully and never share them
 * If your API key is compromised, you can rotate it using the ZenML dashboard or by running the `zenml service-account api-key <SERVICE_ACCOUNT_NAME> rotate` command
 {% endhint %}

docs/book/api-docs/pro-api/pro-api/getting-started.md

@@ -46,71 +46,31 @@ To use the ZenML Pro API, you need to authenticate your requests. If you are log
 
 For example, for the SaaS variant, you can access the docs here: [https://cloudapi.zenml.io](https://cloudapi.zenml.io). 
 
-### Programmatic access with short-lived API tokens
 
-Similar to [short-lived tokens for OSS and Workspace servers](../../oss-api/oss-api/#using-a-short-lived-api-token), API tokens provide a way to authenticate with the ZenML Pro API for temporary automation tasks. These tokens are scoped to your user account and are valid for 1 hour by default. You can use the generated API tokens for programmatic access to the ZenML Pro REST API.
+### Programmatic access with Personal Access Tokens
 
-To generate a new API token for the ZenML Pro API:
-
-1. Navigate to the organization settings page in your ZenML Pro dashboard
-2. Select "API Tokens" from the left sidebar
-
-    ![API Tokens](../../../.gitbook/assets/zenml-pro-api-token-01.png)
-3. Click the "Create new token" button. Once generated, you'll see a dialog showing your new API token.
-
-    ![API Tokens](../../../.gitbook/assets/zenml-pro-api-token-02.png)
-4. Simply use the API token as the bearer token in your HTTP requests. For example, you can use the following command to check your current user:
-   *   using curl:
-
-       ```bash
-       curl -H "Authorization: Bearer YOUR_API_TOKEN" https://cloudapi.zenml.io/users/me
-       ```
-   *   using wget:
-
-       ```bash
-       wget -qO- --header="Authorization: Bearer YOUR_API_TOKEN" https://cloudapi.zenml.io/users/me
-       ```
-   *   using python:
-
-       ```python
-       import requests
-
-       response = requests.get(
-         "https://cloudapi.zenml.io/users/me",
-         headers={"Authorization": f"Bearer YOUR_API_TOKEN"}
-       )
-       print(response.json())
-       ```
-
-{% hint style="info" %}
-**Important Notes**
-
-* API tokens expire after 1 hour and need to be renewed periodically.
-* individual API tokens cannot be revoked after they are generated. If a token is compromised, you may need to lock the user account or service account to prevent further access.
-* Tokens are scoped to the user account or service account that was used to generate them and inherit their permissions.
-* As an alternative to API tokens, you can use [service accounts and API keys](./#programmatic-access-with-service-accounts-and-api-keys) for long-term access.
-{% endhint %}
+Personal Access Tokens are long-lived credentials scoped to your own user account that can be used to authenticate to the ZenML Pro API and the Workspace API across all the organizations and workspaces that your account has access to. See [Personal Access Tokens](https://docs.zenml.io/pro/access-management/personal-access-tokens) for setup and examples.
 
 ### Programmatic access with service accounts and API keys
 
 {% hint style="warning" %}
 **Deprecation of workspace level service accounts and API keys**
 
 * ZenML Pro workspace level service accounts and API keys are deprecated and will be removed in a future version.
-* Please use ZenML Pro organization level service accounts and API keys instead (see [Service Accounts](https://docs.zenml.io/pro/core-concepts/service-accounts))
-* Follow the migration guide in [Migration of workspace level service accounts](https://docs.zenml.io/pro/core-concepts/service-accounts#migration-of-workspace-level-service-accounts) to learn how to migrate from your existing service accounts.
+* Please use ZenML Pro organization level service accounts and API keys instead (see [Service Accounts](https://docs.zenml.io/pro/access-management/service-accounts))
+* Follow the migration guide in [Migration of workspace level service accounts](https://docs.zenml.io/pro/access-management/service-accounts#migration-of-workspace-level-service-accounts) to learn how to migrate from your existing service accounts.
 {% endhint %}
 
-Organization‑level service accounts and API keys can be used to authenticate to the ZenML Pro API and the Workspace API across all workspaces in your organization. See [Service Accounts](https://docs.zenml.io/pro/core-concepts/service-accounts) for setup and examples.
+Organization‑level service accounts and API keys can be used to authenticate to the ZenML Pro API and the Workspace API across all workspaces in your organization. See [Service Accounts](https://docs.zenml.io/pro/access-management/service-accounts) for setup and examples.
 
 ## When to Use Which API
 
 | Task | Use This API | Authentication Method |
 |------|-------------|----------------------|
-| Managing organizations, workspaces, users | **ZenML Pro API** (cloudapi.zenml.io) | Short-lived API tokens from organization settings |
-| Accessing the ZenML Pro API programmatically from external systems | **ZenML Pro API** (cloudapi.zenml.io) | Service accounts + API keys (recommended for automation) |
-| Running snapshots, pipeline operations | **Workspace API** (your workspace URL) | Service accounts + API keys (recommended for automation) |
-| Pipeline development, artifact management | **Workspace API** (your workspace URL) | Temporary API tokens or service accounts |
+| Managing organizations, workspaces, users | **ZenML Pro API** (cloudapi.zenml.io) | Personal Access Tokens |
+| Accessing the ZenML Pro API programmatically from external systems | **ZenML Pro API** (cloudapi.zenml.io) | Service Accounts + API keys (recommended for automation) |
+| Running snapshots, pipeline operations | **Workspace API** (your workspace URL) | Service Accounts + API keys (recommended for automation) |
+| Pipeline development, artifact management | **Workspace API** (your workspace URL) | Personal Access Tokens or Service Accounts + API Keys |
 
 See the high‑level overview: [Connect to a server](https://docs.zenml.io/how-to/manage-zenml-server/connecting-to-zenml#choose-how-to-connect).
 
@@ -120,12 +80,12 @@ The **Workspace API** is different from the ZenML Pro API and supports different
 
 ### Workspace API Authentication Methods
 
-Programmatic access to the ZenML Pro workspace API is achieved mostly the same way as the ZenML OSS server API. This is because the Workspace API in ZenML Pro is an extension of the OSS API with some additional endpoints. The only exception is that workspace level service accounts and API keys are disabled and organization level service accounts and API keys are used instead (see [Service Accounts](https://docs.zenml.io/pro/core-concepts/service-accounts)).
+Programmatic access to the ZenML Pro workspace API is achieved mostly the same way as the ZenML OSS server API. This is because the Workspace API in ZenML Pro is an extension of the OSS API with some additional endpoints. The only exception is that workspace level service accounts and API keys are disabled and organization level service accounts and API keys are used instead (see [Service Accounts](https://docs.zenml.io/pro/access-management/service-accounts)).
 
 You can use one of these two methods to authenticate with your workspace API:
 
-* [Generate and use temporary API tokens](../../oss-api/oss-api/#using-a-short-lived-api-token) (good for development and short-term tasks)
-* [Create a ZenML Pro service account and use its API key](https://docs.zenml.io/pro/core-concepts/service-accounts) (recommended for production automation and run template triggering)
+* [Create and use a Personal Access Token](https://docs.zenml.io/pro/access-management/personal-access-tokens) (good for development and short-term tasks)
+* [Create a ZenML Pro service account and use its API key](https://docs.zenml.io/pro/access-management/service-accounts) (recommended for production automation and run template triggering)
 
 When making requests to the Workspace API, make sure to use your workspace URL as the base URL. This is different from the ZenML Pro API URL (cloudapi.zenml.io), which is used for organization-level operations.
 
@@ -183,7 +143,7 @@ Snapshots allow you to start pipeline runs from external systems using HTTP requ
 {% hint style="success" %}
 **For Snapshot Automation**
 
-When running snapshots from external systems or CI/CD pipelines, we strongly recommend using **service accounts with API keys** rather than temporary tokens. Service accounts provide:
+When running snapshots from external systems or CI/CD pipelines, we strongly recommend using **service accounts with API keys**. Service accounts provide:
 
 * Long-term credentials that don't expire hourly
 * Dedicated authentication for automation (not tied to individual users)
@@ -211,21 +171,21 @@ Use this decision tree to determine the right approach:
 | **What do you want to do?** | **Which API?** | **Authentication Method** | **Why?** |
 |------------------------------|----------------|---------------------------|----------|
 | Run snapshots from CI/CD or external systems | **Workspace API** (your workspace URL) | Service account + API key | Long-lived, automation-friendly, not tied to users |
-| Manage organizations, create workspaces, invite users | **ZenML Pro API** (cloudapi.zenml.io) | Short-lived API tokens from org settings | Administrative operations need user-level permissions |
+| Manage organizations, create workspaces, invite users | **ZenML Pro API** (cloudapi.zenml.io) | Personal Access Tokens | Administrative operations need user-level permissions |
 | Access the ZenML Pro API programmatically from external systems | **ZenML Pro API** (cloudapi.zenml.io) | Service accounts + API keys (recommended for automation) | Long-lived, automation-friendly, not tied to users |
-| Develop pipelines, explore artifacts | **Workspace API** (your workspace URL) | Temporary API tokens or service accounts | Flexible for development needs |
-| One-off pipeline operations | **Workspace API** (your workspace URL) | Temporary API tokens | Quick and easy for manual tasks |
+| Develop pipelines, explore artifacts | **Workspace API** (your workspace URL) | Personal Access Tokens or Service Accounts + API keys | Flexible for development needs |
+| One-off pipeline operations | **Workspace API** (your workspace URL) | Personal Access Tokens | Quick and easy for manual tasks |
 
 ### Common Issues
 
 **"My API calls are getting 401 Unauthorized"**
 - ✅ Check that you're using the correct API URL (workspace URL vs cloudapi.zenml.io)
-- ✅ Verify your token hasn't expired (user tokens expire after 1 hour)
+- ✅ Verify your credentials haven't expired (see next issue)
 - ✅ Ensure you're using `Bearer <token>` format in the Authorization header
 
 **"My automation keeps failing after an hour"**
-- ✅ Switch from temporary API tokens to service account API keys
-- ✅ Service account tokens don't expire automatically like user tokens
+- ✅ Check what type of authentication you are using (Personal Access Tokens or service account API keys)
+- ✅ Check the expiration date of the credentials you are using and rotate them if they have expired. Optionally adjust the expiration time during rotation.
 
 **"I can't find the endpoint to run a snapshot"**
 - ✅ Running snapshots is only possible using the **Workspace API**, not the ZenML Pro API

docs/book/component-guide/component-guide.md

@@ -57,7 +57,7 @@ Here's an approach you can take that is a good balance between convenience and s
 If you follow this approach, you can keep your data scientists free from the hassle of figuring out the best authentication mechanisms for the different cloud services, having to manage credentials locally, and keep your cloud accounts safe, while still giving them the freedom to run their experiments in the cloud.
 
 {% hint style="info" %}
-Please note that restricting permissions for users through roles is a ZenML Pro feature. You can read more about it [here](https://docs.zenml.io/pro/core-concepts/roles). Sign up for a free trial here: https://zenml.io/pro.
+Please note that restricting permissions for users through roles is a ZenML Pro feature. You can read more about it [here](https://docs.zenml.io/pro/access-management/roles). Sign up for a free trial here: https://zenml.io/pro.
 {% endhint %}
 
 ## How to deploy and manage stacks