> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Authentication

> Sign in to the API Reference from ZedUI, generate API tokens in the console or programmatically, and understand token scope, permissions, and expiry.

## Introduction

All requests to the Edge Infrastructure Services API require a token. Tokens are scoped to your enterprise, carry the same permissions as your user account, and expire after the period you choose at creation time.

There are two ways to obtain a token: through the console UI, or programmatically using the login and session endpoints.

### Prerequisites

* You are signed in to Edge Infrastructure Services.
* You have a role with permissions for the operations you plan to perform. For role details, see [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).

## Sign in to the API Reference

Sign in to your usual ZedCloud console, then open **Help & Documentation → API Reference** from your profile menu. Your cluster and authorization are filled in automatically. You do not need to copy a token.

On an endpoint page, select **Try it**, complete the request, check the controller endpoint, and select **Send**. Requests use your existing permissions.

Modifying requests are off by default. To enable POST, PUT, PATCH, or DELETE, open **API request settings**, select **Enable modifying requests**, and choose **Apply settings**. These requests can change live resources.

Reopen API Reference from the console if your session expires or you switch accounts or clusters. Sign out of the console when finished; closing a documentation tab does not sign you out.

## Generate an API Token

1. In the header, select your profile avatar, then select **Profile Settings**.

2. In the Profile Settings navigation, under **Security & Access**, select **API Tokens**.

3. Select **New Token**.

4. Complete the following fields:

   | Field | Description |
   | - | - |
   | **Token Name** | A descriptive name that identifies the token's purpose, for example `CI pipeline` or `local dev`. |
   | **Expiry** | Select a validity period: 1 hour, 1 day, 7 days, 30 days (default), or 90 days. |

5. Select **Generate Token**.

6. Copy the token from the dialog. The token is shown only once. Store it in a secure location such as a secrets manager or environment variable before closing the dialog.

The token appears in the **API Tokens** list with its name, client, and expiry date.

## Authenticate Programmatically

If you are building scripts or automations that call the Edge Infrastructure Services API without a user session, use the two-step programmatic authentication flow to obtain a session token.

Replace `zedcontrol.zededa.net` with your enterprise's Edge Infrastructure Services URL throughout.

### Get your authentication token

Use the `/api/v1/login` endpoint to authenticate with your username and password. This returns a long-lived authentication token. Protect this token, as it has the same rights as your user account.

```text theme={"dark"}
curl --request POST \
  --url https://zedcontrol.zededa.net/api/v1/login \
  --header 'Content-Type: application/json' \
  --data '{
    "usernameAtRealm": "YOUR_EMAIL_ADDRESS",
    "password": "YOUR_PASSWORD"
  }'
```

From the response, note the following values:

| Field | Description |
| - | - |
| `token.base64` | Used as the Bearer token in the next section. |
| `detailedUser.enterpriseId` | Used as `enterpriseId` in the next section. |
| `enterprise.apiTokenExpiryInSeconds` | Used as `expires` in the next section. |

Example response:

```json theme={"dark"}
{
  "cause": "OK",
  "token": {
    "base64": "mK7qZxwE9vL1NcR5GfuIo3sW0pH..."
  },
  "detailedUser": {
    "enterpriseId": "BBFlABAqrlsKjklO242lSkKoCt16"
  },
  "enterprise": {
    "apiTokenExpiryInSeconds": 7776000
  }
}
```

### Get your session token

Use the `/api/v1/sessions/token/self` endpoint with the values from the preceding section to obtain a short-lived session token. Use this session token for all subsequent API requests. When it expires, repeat both sections to get a new one.

```text theme={"dark"}
curl --request POST \
  --url https://zedcontrol.zededa.net/api/v1/sessions/token/self \
  --header 'Authorization: Bearer <token.base64 from previous section>' \
  --header 'Content-Type: application/json' \
  --data '{
    "enterpriseId": "<detailedUser.enterpriseId from previous section>",
    "expires": <enterprise.apiTokenExpiryInSeconds from previous section>
  }'
```

From the response, note the following value:

| Field | Description |
| - | - |
| `apiToken.base64` | The session token to use as the Bearer token in all API requests. |

Example response:

```json theme={"dark"}
{
  "cause": "OK",
  "apiToken": {
    "base64": "Ut9gZmVwE1bKpD_uSjQx-L7rA3cO..."
  }
}
```

### Use the session token

Pass `apiToken.base64` as the Bearer token in all subsequent API requests:

```text theme={"dark"}
curl -X GET \
  'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED' \
  --header 'Authorization: Bearer <apiToken.base64>' \
  --header 'Content-Type: application/json'
```

## Use the Token in API Requests

Include the token in the `Authorization` header of every API request:

```text theme={"dark"}
Authorization: Bearer YOUR_API_TOKEN
```

For example, to retrieve a list of edge nodes:

```text theme={"dark"}
GET https://zedcontrol.zededa.net/api/v1/devices
Authorization: Bearer YOUR_API_TOKEN
```

Replace `zedcontrol.zededa.net` with your enterprise's Edge Infrastructure Services URL and `YOUR_API_TOKEN` with the token you generated.

## Token Scope

API tokens are scoped to your enterprise, not to individual projects. A token grants access to all projects within the enterprise, subject to the permissions of the user account that created it. The enterprise ID is bound to the token at creation time.

## Token Expiry and Rotation

Tokens expire after the validity period you select at creation time. The available options are 1 hour, 1 day, 7 days, 30 days (default), and 90 days.

Tokens expiring within 7 days are marked with a warning indicator in the **API Tokens** list. Expired tokens are shown as struck through and marked as expired.

There is no automatic renewal or rotation. When a token expires, generate a new one and update any automation or integration that depends on it.

Enterprise administrators can set an enterprise-wide token expiry limit. If this limit is changed, it might invalidate existing tokens that exceed the new limit.

## Least-Privilege Guidance

API tokens inherit the full set of permissions of the user account that created them. There is no mechanism to scope a token to fewer permissions than the user has.

For automation, CI/CD pipelines, and integrations, create a dedicated service user account with the minimum role required for the workflow, then generate tokens from that account. This limits the blast radius if a token is compromised.

For available role definitions and their permissions, see [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).

## Revoke a Token

To revoke a token before it expires:

1. In the header, select your profile avatar, then select **Profile Settings**.
2. In the Profile Settings navigation, under **Security & Access**, select **API Tokens**.
3. Hover over the token row to reveal the delete button.
4. Select the delete button on the token row.
5. In the confirmation dialog, select **Revoke Token**.

Revoked tokens are immediately invalidated. Any automated process using that token needs to be updated with a new one.

## Security Best Practices

### HTTPS and Bearer tokens

When you use the `Authorization: Bearer <YOUR_TOKEN>` header with curl, the token is not sent in clear text over the network as long as you are using HTTPS. Clear text over the network means the data is unencrypted and readable by anyone who intercepts traffic, which can happen with plain HTTP. HTTPS (SSL/TLS) encrypts the connection end to end.

When you run a request like the following:

```text theme={"dark"}
curl -X 'GET' \
'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED' \
--header 'Authorization: Bearer YOUR_SESSION_TOKEN' \
--header 'Content-Type: application/json'
```

The following happens:

1. curl establishes a secure, encrypted TLS tunnel with `zedcontrol.zededa.net`.
2. All data sent within the tunnel (including HTTP headers such as `Authorization`, the request body, and the response) is encrypted.
3. An eavesdropper on the network cannot read the token because it is inside the encrypted tunnel.

The `Authorization: Bearer` header is the secure way to transmit a token over the network, provided you are using HTTPS.

A separate concern is the token appearing in shell history or being visible locally. The strategies below address this.

### Read from a file

Store your token in a file with strict permissions, then pass the file to curl. This is common in automation and scripts.

* Advantages: Token is not directly in shell history. File permissions protect it.
* Disadvantages: Token is still stored on disk.

1. Create a file that contains your token:

   ```text theme={"dark"}
   echo "Authorization: Bearer YOUR_ACTUAL_TOKEN_HERE" > ~/.my_api_token.txt
   ```

2. Restrict the file to owner-only access:

   ```text theme={"dark"}
   chmod 600 ~/.my_api_token.txt
   ```

3. Use the file in your curl command:

   ```text theme={"dark"}
   curl -X GET -H '@~/.my_api_token.txt' 'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED'
   ```

### Read from an environment variable

Export the token as an environment variable for the duration of your session.

* Advantages: Token is not in shell history. It is not stored persistently on disk.
* Disadvantages: Briefly in memory. If someone can access your shell process (for example, via `ps -ef` or `cat /proc/<pid>/environ`), they might see it before you unset it.

1. Export the token as a variable:

   ```text theme={"dark"}
   export API_TOKEN="YOUR_ACTUAL_TOKEN_HERE"
   ```

2. Use the variable in your curl command:

   ```text theme={"dark"}
   curl -X GET -H "Authorization: Bearer $API_TOKEN" 'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED'
   ```

3. Unset the variable when you are done:

   ```text theme={"dark"}
   unset API_TOKEN
   ```

### Prompt for input

For infrequent manual operations, prompt your shell for the token so it never appears on screen or in history.

* Advantages: Token never appears on screen or in history.
* Disadvantages: Requires manual entry each time.

1. Prompt for the token:

   ```text theme={"dark"}
   read -s -p "Enter your Bearer Token: " API_TOKEN_INPUT
   ```

2. Enter your token at the prompt.

3. Use the variable in your curl command:

   ```text theme={"dark"}
   curl -X GET -H "Authorization: Bearer $API_TOKEN_INPUT" 'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED'
   ```

4. Unset the variable when you are done:

   ```text theme={"dark"}
   unset API_TOKEN_INPUT
   ```

### Use a credential helper or manager

For CI/CD pipelines and production workflows, integrate with a dedicated secrets manager such as HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or Google Secret Manager. Your script requests the token from the manager at runtime rather than storing it directly.

* Advantages: Centralized, auditable storage with access control and automatic rotation.
* Disadvantages: Requires setup and integration with a separate system.

For Terraform-managed infrastructure, use the `TF_VAR_` prefix pattern described in [ZEDEDA Terraform Provider](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/terraform-provider.md#protect-secrets).

### Summary

For secure transmission over the network, always use HTTPS. The `Authorization: Bearer` header within HTTPS is the standard, secure method.

For local security, use one of the following approaches ranked by convenience and security trade-off:

* Read from a file with `chmod 600` permissions.
* Read from an environment variable and unset it after use.
* Prompt for input for sensitive one-off operations.
* Use a dedicated secrets manager for enterprise and CI/CD workflows.

## Next Steps

* [How to Use the ZEDEDA API](https://zededa.mintlify.site/api-reference/how-to-use-zededa-api.md): Make your first API request and explore available endpoints.
* [Errors](https://zededa.mintlify.site/api-reference/errors.md): HTTP error codes and how to resolve authentication failures.
* [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md): Role definitions and permissions for least-privilege token setup.
* [Profile Settings](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/profile-settings.md): Overview of all sections in the Profile Settings page, including the API Tokens list.