How to use ZEDEDA API

The ZEDEDA API is a powerful way to interact with the ZEDEDA platform. The following procedures explain how to get started with it.

ZEDEDA GUI Procedures

Get your session token

1. Go to the ZEDEDA GUI.
2. Click on your user profile icon.
3. Hover over your username and then click on User Details.
4. In the Session Information section, click on Click here to request the session token.
5. Copy your token.

Authenticate

1. Go to the Swagger webpage: zedcontrol.zededa.net/api/v1/docs/
   

   Note that you can test directly against your own cluster using the following syntax: 

   https://zedcontrol.YOUR_CLUSTER_NAME.zededa.net/api/v1/docs/

2. Click on Authorize.
3. Enter your session token in the Value field. Make sure to type bearer:
   

   bearer YOUR_SESSION_TOKEN

4. Click on Authorize.
5. Click on Close.

Try one of our APIs

1. Select the desired API.
2. Click on Try it out.
3. Click on Execute.

ZEDEDA API Procedures

Each request against the ZEDEDA Cloud API requires a token, known as a session token. To get a session token, there are two steps:

1. Use your personal credentials, such as username and password, to authenticate and get a long-lived authentication token. Protect this token as it has the same rights you have and it lasts a long time. 
2. Use your long-lived authentication token to get a short-lived session token. This is the token that can be used with each API request.

Authenticate

1. Use the /api/v1/login endpoint to authenticate against ZEDEDA Cloud with your username and password.

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

2. In the response, take note of the following parameter values.
   • token.base64: This value will be used for Bearer token in the next step.
   • detailedUser.enterpriseId: This value will be used for enterpriseId in the next step.
   • enterprise.apiTokenExpiryInSeconds: This value will be used for expires in the next step.

     Response:
     {
     	"cause": "OK",
     	"userId": "AAF1ABBFudD_VeVO2KEGptFvSbiP",
     	"token": {
     		"base64": "mK7qZxwE9vL1NcR5GfuIo3sW0pHdAtVrB9YyXcZ6oP8a_S-l2KjHnMbV4fEgQtUj1xOaS7dRmC3pIeYoWzN-8w_T2bYgL9qKcJvE5rPzQ",
     		...
     	},
     ...
     	"detailedUser": {
     		...
     		"enterpriseId": "BBFlABAqrlsKjklO242lSkKoCt16",
     		...
     	},
     ...
     	"enterprise": {
     		...
     		"apiTokenExpiryInSeconds": 7776000
     	},...
     }

Get your session token

1. Use the /api/v1/sessions/token/self endpoint with the parameter values you noted for Bearer token, enterpriseId, and expires. This creates your session token for access to your enterprise. When it expires, you need a new session token.

   curl --request POST \
   --url https://zedcontrol.zededa.net/api/v1/sessions/token/self \
   --header 'Authorization: Bearer mK7qZxwE9vL1NcR5GfuIo3sW0pHdAtVrB9YyXcZ6oP8a_S-l2KjHnMbV4fEgQtUj1xOaS7dRmC3pIeYoWzN-8w_T2bYgL9qKcJvE5rPzQ' \
   --header 'Content-Type: application/json' \
   --header 'User-Agent: insomnia/10.3.0' \
   --data '{"enterpriseId":"BBFlABAqrlsKjklO242lSkKoCt16","expires": 7776000}'

2. In the response, take note of the following parameter value, which is different from the first token:
   • apiToken.base64: This is the session token value that will be used for the Bearer token in the next step (and in any further API calls that you might make).

     Response:
     {
     "cause": "OK",
     ...
     "apiToken": {
     "base64": "Ut9gZmVwE1bKpD_uSjQx-L7rA3cOhYsP0iNfWn2oMeRz4Uv8IqXa6JkByC5GTEH_VsF1dZpQlOuKmJwCexS2hNi7gYtOrPaDbXvE8fM-cUzAnRIs5qBk9oHwL3TdY_6j4mVsF1dZpQlOuKmJwCexS2hNi7g=",
     "...
     }

Try one of our APIs

Use the desired API endpoint, such as /api/v1/devices, with the session token as the Bearer token.  

curl -X 'GET' \
'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED' \
--header 'Authorization: Bearer Ut9gZmVwE1bKpD_uSjQx-L7rA3cOhYsP0iNfWn2oMeRz4Uv8IqXa6JkByC5GTEH_VsF1dZpQlOuKmJwCexS2hNi7gYtOrPaDbXvE8fM-cUzAnRIs5qBk9oHwL3TdY_6j4mVsF1dZpQlOuKmJwCexS2hNi7g=' \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/10.3.0'

ZEDEDA API Security

When you use the Authorization: Bearer <YOUR_TOKEN> header with curl, you’re not sending the token in clear text over the network if you’re using HTTPS. "Clear text over the network" means the data is unencrypted and readable by anyone who intercepts the network traffic (for example, sniffing packets). This can happen with HTTP.

The primary and standard method for secure transmission of a Bearer token is to use HTTPS (SSL/TLS encryption) for your API endpoint. When you execute a command similar to the following, using HTTPS:

curl -X 'GET' \
'https://zedcontrol.zededa.net/api/v1/devices?adminState=UNSPECIFIED' \
--header 'Authorization: Bearer Ut9gZmVwE1bKpD_uSjQx-L7rA3cOhYsP0iNfWn2oMeRz4Uv8IqXa6JkByC5GTEH_VsF1dZpQlOuKmJwCexS2hNi7gYtOrPaDbXvE8fM-cUzAnRIs5qBk9oHwL3TdY_6j4mVsF1dZpQlOuKmJwCexS2hNi7g=' \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/10.3.0'

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

Therefore, the Authorization: Bearer <YOUR_TOKEN> header is the secure way to transmit the token over the network, provided you are using HTTPS.

A valid, but separate, concern is about the token appearing in shell history or being visible locally. To mitigate the risk you can use the following strategies.

Read from a file

Store your token in a file with strict permissions (e.g., chmod 600 token.txt). Then tell curl to read the header from that file. This is quite common & often recommended for automation/scripts.

• Advantages: Token is not directly in shell history. Permissions protect the file.
• Disadvantages: Still stored on disk.

To read the token from a file, consider an approach similar to the following steps.

1. Create a file with a name such as my_api_token.txt that contains your token.

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

2. Change the permissions on the file, so that it’s only readable by owner.

   chmod 600 ~/.my_api_token.txt

3. 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

Reading from a variable is good for temporary use in a session.

• Advantages: Token not in shell history. Not stored persistently on disk.
• Disadvantages: Still briefly in memory. If someone can access your shell (for example, ps -ef, cat /proc/<pid>/environ), they might see it before you unset it.

To read the token from a variable, consider an approach similar to the following steps.

1. Export the token as a variable with a name such as API_TOKEN.

   export API_TOKEN="YOUR_ACTUAL_TOKEN_HERE"

2. Use the variable in your curl command.

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

3. Unset your variable to clean it up.

   unset API_TOKEN

Prompt for input

Prompting for input is good for interactive use. For highly sensitive, infrequent manual operations, you can have your script or even the shell prompt you for the token, preventing it from being typed directly.

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

To prompt for input, consider an approach similar to the following steps.

1. Tell the shell to prompt you for your token, and set a variable with a name such as API_TOKEN_INPUT.

   bash-3.2$ read -s -p "Enter your Bearer Token: " API_TOKEN_INPUT

2. Enter your token at the prompt.

   Response: 
   Enter your Bearer Token: YOUR_ACTUAL_TOKEN_HERE

3. Use the token variable in your curl command.

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

4. Unset your variable to clean it up.

   unset API_TOKEN_INPUT

Use a credential helper or manager

A credential helper is the most robust for complex workflows. For advanced scenarios, especially in development environments or CI/CD pipelines, integrate with a dedicated credential manager (for example, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager). Your application or script requests the token from the manager at runtime, rather than storing it directly.

• Advantages: Centralized, highly secure storage and retrieval of credentials. Rotation, auditing, and access control are handled by the manager.
• Disadvantages: Requires setup and integration with a separate system.

Summary

For secure transmission over the network always use HTTPS with curl. The Authorization: Bearer header within HTTPS is the standard and secure way.

For local security (preventing history/disk storage) use methods like reading from a file, environment variables, or prompting for input. For enterprise-grade security, integrate with a dedicated secrets management solution.