Authentication

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.

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

In the header, select your profile avatar, then select Profile Settings.
In the Profile Settings navigation, under Security & Access, select API Tokens.
Select New Token.

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.

Select Generate Token.
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.

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:

{
  "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.

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:

{
  "cause": "OK",
  "apiToken": {
    "base64": "Ut9gZmVwE1bKpD_uSjQx-L7rA3cO..."
  }
}

Use the session token

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

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:

Authorization: Bearer YOUR_API_TOKEN

For example, to retrieve a list of edge nodes:

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.

Revoke a Token

To revoke a token before it expires:

In the header, select your profile avatar, then select Profile Settings.
In the Profile Settings navigation, under Security & Access, select API Tokens.
Hover over the token row to reveal the delete button.
Select the delete button on the token row.
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:

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:

curl establishes a secure, encrypted TLS tunnel with zedcontrol.zededa.net.
All data sent within the tunnel (including HTTP headers such as Authorization, the request body, and the response) is encrypted.
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.

Create a file that contains your token:

echo "Authorization: Bearer YOUR_ACTUAL_TOKEN_HERE" > ~/.my_api_token.txt

Restrict the file to owner-only access:
chmod 600 ~/.my_api_token.txt

Use the file in your curl command:

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.

Export the token as a variable:

export API_TOKEN="YOUR_ACTUAL_TOKEN_HERE"

Use the variable in your curl command:

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

Unset the variable when you are done:
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.

Prompt for the token:

read -s -p "Enter your Bearer Token: " API_TOKEN_INPUT

Enter your token at the prompt.

Use the variable in your curl command:

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

Unset the variable when you are done:
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.

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: Make your first API request and explore available endpoints.
Errors: HTTP error codes and how to resolve authentication failures.
Manage Roles: Role definitions and permissions for least-privilege token setup.
Profile Settings: Overview of all sections in the Profile Settings page, including the API Tokens list.

API guides

API services

Introduction

Prerequisites

Generate an API Token

Authenticate Programmatically

Get your authentication token

Get your session token

Use the session token

Use the Token in API Requests

Token Scope

Token Expiry and Rotation

Least-Privilege Guidance

Revoke a Token

Security Best Practices

HTTPS and Bearer tokens

Read from a file

Read from an environment variable

Prompt for input

Use a credential helper or manager

Summary

Next Steps

​Introduction

​Prerequisites

​Sign in to the API Reference

​Generate an API Token

​Authenticate Programmatically

​Get your authentication token

​Get your session token

​Use the session token

​Use the Token in API Requests

​Token Scope

​Token Expiry and Rotation

​Least-Privilege Guidance

​Revoke a Token

​Security Best Practices

​HTTPS and Bearer tokens

​Read from a file

​Read from an environment variable

​Prompt for input

​Use a credential helper or manager

​Summary

​Next Steps

Introduction

Prerequisites

Sign in to the API Reference

Generate an API Token

Authenticate Programmatically

Get your authentication token

Get your session token

Use the session token

Use the Token in API Requests

Token Scope

Token Expiry and Rotation

Least-Privilege Guidance

Revoke a Token

Security Best Practices

HTTPS and Bearer tokens

Read from a file

Read from an environment variable

Prompt for input

Use a credential helper or manager

Summary

Next Steps