Getting Started

The ZenML OSS server is a FastAPI application, therefore the OpenAPI-compliant docs are available at /docs or /redoc of your ZenML server:

In the local case (i.e. using zenml login --local, the docs are available on http://127.0.0.1:8237/docs)

ZenML API docs

Difference between OpenAPI docs and ReDoc

The OpenAPI docs (/docs) provide an interactive interface where you can try out the API endpoints directly from the browser. It is useful for testing and exploring the API functionalities.

ReDoc (/redoc), on the other hand, offers a more static and visually appealing documentation. It is designed for better readability and is ideal for understanding the API structure and reference.

ZenML API Redoc

Accessing the ZenML OSS API

For OSS users: The server_url is the root URL of your ZenML server deployment.

If you are using the ZenML OSS server API using the methods displayed above, it is enough to be logged in to your ZenML account in the same browser session. However, in order to do this programmatically, you can use one of the methods documented in the following sections.

Choosing a method:

• Humans at the CLI: use interactive login.

• CI/CD and automation: use service accounts + API keys.

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.

Start by creating a service account and an API key, e.g.:

```shell
zenml service-account create myserviceaccount
```

Then, there are two methods to authenticate with the API using the API key - one is simpler but less secure, the other is secure and recommended but more complex:

Direct API key authentication

This approach, albeit simple, is not recommended because the long-lived API key is exposed with every API request, which makes it easier to be compromised. Use it only in low-risk circumstances.

Use the API key directly to authenticate your API requests by including it in the Authorization header. For example, you can use the following command to check your current user:

• using curl:

  curl -H "Authorization: Bearer YOUR_API_KEY" https://your-zenml-server/api/v1/current-user

• using wget:

  wget -qO- --header="Authorization: Bearer YOUR_API_KEY" https://your-zenml-server/api/v1/current-user

• using python:

  import requests
  
  response = requests.get(
      "https://your-zenml-server/api/v1/current-user",
      headers={"Authorization": f"Bearer {YOUR_API_KEY}"}
  )
  
  print(response.json())

Token exchange authentication

Important notes

• 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 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