# Authentication
Source: https://developers.onidel.com/api-reference/authentication

How to create an API token and use it to authenticate with Onidel

## Introduction

Onidel's API uses **API tokens** to authenticate and authorize requests. An API token acts as a secure credential that allows you to interact programmatically with the Onidel platform.

Each API token carries the **same permissions as the user** who generated it. For this reason, tokens should be treated with the same level of security as your account credentials.

By including your API token in requests, you can manage infrastructure, automate workflows, and integrate Onidel services directly into your applications.

## Create API token

To create an API token:

1. Navigate to [Account Settings](https://cloud.onidel.com/account/settings).
2. Select the **API Key** tab.
3. Copy the generated API key.

<Tip>
  Click the **Rotate** button to expire this key and generate a new one.
</Tip>

## Authenticate

To authenticate your request with Onidel, include the token in the `Authorization` header:

```bash theme={null}
curl -vv https://api.cloud.onidel.com/ -H "Authorization: Bearer <YOUR_TOKEN>"
```

## Security Best Practices

### Keep your token secure

Never share your API token publicly or include it in client-side code that can be accessed by users.

### Whitelist trusted IPs only

Configure IP whitelisting to restrict access to known and trusted IP addresses. This adds an additional layer of security, ensuring that only trusted sources can access the API.

### Rotate your API token regularly

Periodically regenerate your API token to minimise the impact of potential exposure.

### Use environment variables

Store your API token in environment variables or a secure secret manager to keep it out of your codebase.


# Generate backup download URL
Source: https://developers.onidel.com/api-reference/backups/generate-backup-download-url

/api-reference/openapi.yaml post /backups/{backup_id}
Generate backup download URL



# List backups
Source: https://developers.onidel.com/api-reference/backups/list-backups

/api-reference/openapi.yaml get /backups
List backups available to the user



# Create an ISO from a URL
Source: https://developers.onidel.com/api-reference/custom-iso/create-an-iso-from-a-url

/api-reference/openapi.yaml post /isos
Register a custom ISO by URL. The file is downloaded asynchronously;
poll the ISO's status (download percent) until it reaches 100. Subject
to the per-team ISO count and maximum file size limits.



# Delete an ISO
Source: https://developers.onidel.com/api-reference/custom-iso/delete-an-iso

/api-reference/openapi.yaml delete /isos/{iso_id}
Delete a custom ISO. The ISO must not be attached to any non-terminated instance.



# Get an ISO by UUID
Source: https://developers.onidel.com/api-reference/custom-iso/get-an-iso-by-uuid

/api-reference/openapi.yaml get /isos/{iso_id}
Get a single ISO, including its download status.



# List ISOs
Source: https://developers.onidel.com/api-reference/custom-iso/list-isos

/api-reference/openapi.yaml get /isos
List the team's custom ISOs along with available system ISOs.



# Create Firewall Rule
Source: https://developers.onidel.com/api-reference/firewall-rule/create-firewall-rule

/api-reference/openapi.yaml post /network/firewalls/{firewall_id}/rules
Add a new rule to a firewall group.

Special subnet values: `Cloudflare`, `Onidel`, `HetrixTools`, `CloudFront`, `UptimeRobot`.
To reference an IP list, use `list:{ip_list_id}` as the subnet value.



# Delete Firewall Rule
Source: https://developers.onidel.com/api-reference/firewall-rule/delete-firewall-rule

/api-reference/openapi.yaml delete /network/firewalls/{firewall_id}/rules/{rule_id}
Delete a firewall rule from a group



# Get Firewall Rule by ID
Source: https://developers.onidel.com/api-reference/firewall-rule/get-firewall-rule-by-id

/api-reference/openapi.yaml get /network/firewalls/{firewall_id}/rules/{rule_id}
Retrieve a specific firewall rule



# List Firewall Rules
Source: https://developers.onidel.com/api-reference/firewall-rule/list-firewall-rules

/api-reference/openapi.yaml get /network/firewalls/{firewall_id}/rules
Retrieve all rules in a firewall group



# Update Firewall Rule
Source: https://developers.onidel.com/api-reference/firewall-rule/update-firewall-rule

/api-reference/openapi.yaml patch /network/firewalls/{firewall_id}/rules/{rule_id}
Update a firewall rule's description (max 255 characters)



# Create Firewall Group
Source: https://developers.onidel.com/api-reference/firewall/create-firewall-group

/api-reference/openapi.yaml post /network/firewalls
Create a new firewall group



# Delete Firewall Group
Source: https://developers.onidel.com/api-reference/firewall/delete-firewall-group

/api-reference/openapi.yaml delete /network/firewalls/{firewall_id}
Delete a firewall group. Cannot delete if VMs are still attached.



# Get Firewall Group by ID
Source: https://developers.onidel.com/api-reference/firewall/get-firewall-group-by-id

/api-reference/openapi.yaml get /network/firewalls/{firewall_id}
Retrieve a specific firewall group by its UUID



# List Firewall Groups
Source: https://developers.onidel.com/api-reference/firewall/list-firewall-groups

/api-reference/openapi.yaml get /network/firewalls
Retrieve all firewall groups for a team



# Update Firewall Group
Source: https://developers.onidel.com/api-reference/firewall/update-firewall-group

/api-reference/openapi.yaml put /network/firewalls/{firewall_id}
Update a firewall group's description



# Get VM Price
Source: https://developers.onidel.com/api-reference/instance-price/get-vm-price

/api-reference/openapi.yaml get /instance_price
Get VM price based on the specified VM configuration parameters.



# List Instance Types
Source: https://developers.onidel.com/api-reference/instance-type/list-instance-types

/api-reference/openapi.yaml get /instance_types
List instance types available for provision



# Add Entry to IP List
Source: https://developers.onidel.com/api-reference/ip-list/add-entry-to-ip-list

/api-reference/openapi.yaml post /network/ip_lists/{ip_list_id}/entries
Add an IP address or CIDR to an IP list. Type is auto-detected if not provided.
Supports IPv4 and IPv6 addresses and CIDR ranges. The `/0` prefix is not allowed.



# Create IP List
Source: https://developers.onidel.com/api-reference/ip-list/create-ip-list

/api-reference/openapi.yaml post /network/ip_lists
Create a new IP list. Limit per team is configurable.



# Delete Entry from IP List
Source: https://developers.onidel.com/api-reference/ip-list/delete-entry-from-ip-list

/api-reference/openapi.yaml delete /network/ip_lists/{ip_list_id}/entries/{entry_id}
Remove an entry from an IP list



# Delete IP List
Source: https://developers.onidel.com/api-reference/ip-list/delete-ip-list

/api-reference/openapi.yaml delete /network/ip_lists/{ip_list_id}
Delete an IP list. All firewall rules referencing this list will also be removed.



# Get IP List by ID
Source: https://developers.onidel.com/api-reference/ip-list/get-ip-list-by-id

/api-reference/openapi.yaml get /network/ip_lists/{ip_list_id}
Retrieve a specific IP list with all its entries



# List IP Lists
Source: https://developers.onidel.com/api-reference/ip-list/list-ip-lists

/api-reference/openapi.yaml get /network/ip_lists
Retrieve all IP lists for a team. The response also includes the team's limits: ip_list_limit (maximum lists) and ip_list_entry_limit (maximum entries per list).



# Update IP List
Source: https://developers.onidel.com/api-reference/ip-list/update-ip-list

/api-reference/openapi.yaml patch /network/ip_lists/{ip_list_id}
Update an IP list's name or description



# Delete a measured boot image
Source: https://developers.onidel.com/api-reference/measured-boot-image/delete-a-measured-boot-image

/api-reference/openapi.yaml delete /measured-boot-images/{image_id}
Delete a measured boot image. It must not be attached to any instance.



# List measured boot images
Source: https://developers.onidel.com/api-reference/measured-boot-image/list-measured-boot-images

/api-reference/openapi.yaml get /measured-boot-images
List the team's measured direct boot images (UKIs).



# Upload a measured boot image
Source: https://developers.onidel.com/api-reference/measured-boot-image/upload-a-measured-boot-image

/api-reference/openapi.yaml post /measured-boot-images
Upload a UKI (unified kernel image bundling kernel, initrd and cmdline)
for SEV-SNP measured direct boot. Subject to the maximum file size limit.



# Create a Bucket
Source: https://developers.onidel.com/api-reference/object-storage/create-a-bucket

/api-reference/openapi.yaml post /object-storage/{service_id}/buckets
Create a new bucket in the object storage service



# Get Bucket Access Keys
Source: https://developers.onidel.com/api-reference/object-storage/get-bucket-access-keys

/api-reference/openapi.yaml get /object-storage/{service_id}/buckets/{bucket_name}/access_keys
Retrieve access keys for a specific bucket



# Get Object Storage Service
Source: https://developers.onidel.com/api-reference/object-storage/get-object-storage-service

/api-reference/openapi.yaml get /object-storage/{service_id}
Retrieve details of a specific object storage service



# List Object Storage Services
Source: https://developers.onidel.com/api-reference/object-storage/list-object-storage-services

/api-reference/openapi.yaml get /object-storage
Retrieve all object storage services for the team



# List OS Templates
Source: https://developers.onidel.com/api-reference/os-template/list-os-templates

/api-reference/openapi.yaml get /os_templates
List prebuilt OS images available for installation.



# Convert VM's primary IP to reserved IP
Source: https://developers.onidel.com/api-reference/reserved-ips/convert-vms-primary-ip-to-reserved-ip

/api-reference/openapi.yaml post /network/reserved_ips/convert
Convert an existing VM's primary public IP address into a reserved IP (floating IP)



# Create a new reserved IP
Source: https://developers.onidel.com/api-reference/reserved-ips/create-a-new-reserved-ip

/api-reference/openapi.yaml post /network/reserved_ips
Allocate a new reserved IP address in the specified location



# Delete a reserved IP
Source: https://developers.onidel.com/api-reference/reserved-ips/delete-a-reserved-ip

/api-reference/openapi.yaml delete /network/reserved_ips/{reserved_ip_id}
Terminate a reserved IP and release it back to the pool. Will automatically detach from VM if attached.



# Get a specific reserved IP
Source: https://developers.onidel.com/api-reference/reserved-ips/get-a-specific-reserved-ip

/api-reference/openapi.yaml get /network/reserved_ips/{reserved_ip_id}
Retrieve details of a specific reserved IP by ID



# List reserved IPs
Source: https://developers.onidel.com/api-reference/reserved-ips/list-reserved-ips

/api-reference/openapi.yaml get /network/reserved_ips
Get all reserved IPs for the authenticated user's team or specified team



# Update reserved IP (rename or attach/detach VM)
Source: https://developers.onidel.com/api-reference/reserved-ips/update-reserved-ip-rename-or-attachdetach-vm

/api-reference/openapi.yaml patch /network/reserved_ips/{reserved_ip_id}
Update reserved IP properties - rename it or attach/detach it to/from a VM



# Delete a snapshot
Source: https://developers.onidel.com/api-reference/snapshots/delete-a-snapshot

/api-reference/openapi.yaml delete /snapshots/{snapshot_id}
Delete a snapshot



# Generate snapshot download URL
Source: https://developers.onidel.com/api-reference/snapshots/generate-snapshot-download-url

/api-reference/openapi.yaml post /snapshots/{snapshot_id}
Generate snapshot download URL



# List snapshots
Source: https://developers.onidel.com/api-reference/snapshots/list-snapshots

/api-reference/openapi.yaml get /snapshots
List snapshots available to the user



# Create a new SSH Key
Source: https://developers.onidel.com/api-reference/ssh-key/create-a-new-ssh-key

/api-reference/openapi.yaml post /ssh_keys
Add a new SSH key to the team



# Delete SSH Key
Source: https://developers.onidel.com/api-reference/ssh-key/delete-ssh-key

/api-reference/openapi.yaml delete /ssh_keys/{ssh_key_id}
Delete an SSH key



# Get SSH Key by ID
Source: https://developers.onidel.com/api-reference/ssh-key/get-ssh-key-by-id

/api-reference/openapi.yaml get /ssh_keys/{ssh_key_id}
Retrieve a specific SSH key by its UUID



# List SSH Keys
Source: https://developers.onidel.com/api-reference/ssh-key/list-ssh-keys

/api-reference/openapi.yaml get /ssh_keys
Retrieve all SSH keys for a team



# Update SSH Key
Source: https://developers.onidel.com/api-reference/ssh-key/update-ssh-key

/api-reference/openapi.yaml patch /ssh_keys/{ssh_key_id}
Update an existing SSH key



# Create a new Startup Script
Source: https://developers.onidel.com/api-reference/startup-script/create-a-new-startup-script

/api-reference/openapi.yaml post /startup_scripts
Add a new startup script to the team. Maximum 10 scripts per team.



# Delete Startup Script
Source: https://developers.onidel.com/api-reference/startup-script/delete-startup-script

/api-reference/openapi.yaml delete /startup_scripts/{script_id}
Delete a startup script



# Get Startup Script by ID
Source: https://developers.onidel.com/api-reference/startup-script/get-startup-script-by-id

/api-reference/openapi.yaml get /startup_scripts/{script_id}
Retrieve a specific startup script by its UUID, including content



# List Startup Scripts
Source: https://developers.onidel.com/api-reference/startup-script/list-startup-scripts

/api-reference/openapi.yaml get /startup_scripts
Retrieve all startup scripts for a team



# Update Startup Script
Source: https://developers.onidel.com/api-reference/startup-script/update-startup-script

/api-reference/openapi.yaml patch /startup_scripts/{script_id}
Update an existing startup script



# List Teams
Source: https://developers.onidel.com/api-reference/teams/list-teams

/api-reference/openapi.yaml get /teams
Retrieve all teams the user is a member of



# Attach a measured boot image
Source: https://developers.onidel.com/api-reference/virtual-machine/attach-a-measured-boot-image

/api-reference/openapi.yaml post /vm/{vm_id}/attach-measured-boot
Attach a measured boot image (UKI) to the VM and power-cycle to apply it. SEV-SNP must already be enabled.



# Delete a reverse DNS (PTR) record
Source: https://developers.onidel.com/api-reference/virtual-machine/delete-a-reverse-dns-ptr-record

/api-reference/openapi.yaml delete /vm/{vm_id}/rdns/{ip_addr}
Delete the reverse DNS record for one of the VM's IP addresses.



# Destroy the VM
Source: https://developers.onidel.com/api-reference/virtual-machine/destroy-the-vm

/api-reference/openapi.yaml delete /vm/{vm_id}
Destroy the VM



# Detach the measured boot image
Source: https://developers.onidel.com/api-reference/virtual-machine/detach-the-measured-boot-image

/api-reference/openapi.yaml post /vm/{vm_id}/detach-measured-boot
Clear the VM's measured boot image and power-cycle to apply.



# Disable BGP
Source: https://developers.onidel.com/api-reference/virtual-machine/disable-bgp

/api-reference/openapi.yaml post /vm/{vm_id}/disable-bgp
Disable BGP for the VM.



# Enable BGP
Source: https://developers.onidel.com/api-reference/virtual-machine/enable-bgp

/api-reference/openapi.yaml post /vm/{vm_id}/enable-bgp
Enable BGP for the VM (requires an active BGP session in the location).



# Get a VM by UUID
Source: https://developers.onidel.com/api-reference/virtual-machine/get-a-vm-by-uuid

/api-reference/openapi.yaml get /vm/{vm_id}
Gets a VM by its UUID



# Get all backups of the VM
Source: https://developers.onidel.com/api-reference/virtual-machine/get-all-backups-of-the-vm

/api-reference/openapi.yaml get /vm/{vm_id}/backups
Get all backups of the VM



# List reverse DNS (PTR) records
Source: https://developers.onidel.com/api-reference/virtual-machine/list-reverse-dns-ptr-records

/api-reference/openapi.yaml get /vm/{vm_id}/rdns
List the reverse DNS records configured for the VM's IP addresses.



# List VMs
Source: https://developers.onidel.com/api-reference/virtual-machine/list-vms

/api-reference/openapi.yaml get /vm
List all VMs available to the user



# Open a noVNC console session
Source: https://developers.onidel.com/api-reference/virtual-machine/open-a-novnc-console-session

/api-reference/openapi.yaml post /vm/{vm_id}/vnc
Creates a noVNC console session for the specified VM.
Returns a URL to access the VM console via noVNC in a browser.
The session token expires after 30 seconds if not used.



# Provision a new VM
Source: https://developers.onidel.com/api-reference/virtual-machine/provision-a-new-vm

/api-reference/openapi.yaml post /vm
Provision a new VM



# Reboot a VM
Source: https://developers.onidel.com/api-reference/virtual-machine/reboot-a-vm

/api-reference/openapi.yaml post /vm/{vm_id}/reboot
Reboot the VM.



# Restore a VM from a backup
Source: https://developers.onidel.com/api-reference/virtual-machine/restore-a-vm-from-a-backup

/api-reference/openapi.yaml post /vm/{vm_id}/restore-backup
Restore a VM from a backup.



# Restore a VM from a snapshot
Source: https://developers.onidel.com/api-reference/virtual-machine/restore-a-vm-from-a-snapshot

/api-reference/openapi.yaml post /vm/{vm_id}/restore-snapshot
Restore a VM from a snapshot.



# Set a reverse DNS (PTR) record
Source: https://developers.onidel.com/api-reference/virtual-machine/set-a-reverse-dns-ptr-record

/api-reference/openapi.yaml post /vm/{vm_id}/rdns
Set the reverse DNS record for one of the VM's IP addresses. The domain
must already resolve (A/AAAA) to the IP being configured.



# Stop a VM
Source: https://developers.onidel.com/api-reference/virtual-machine/stop-a-vm

/api-reference/openapi.yaml post /vm/{vm_id}/stop
Gracefully shut down the VM.



# Take a snapshot
Source: https://developers.onidel.com/api-reference/virtual-machine/take-a-snapshot

/api-reference/openapi.yaml post /vm/{vm_id}/snapshot
Take a snapshot of the VM.



# Update VM configuration
Source: https://developers.onidel.com/api-reference/virtual-machine/update-vm-configuration

/api-reference/openapi.yaml patch /vm/{vm_id}
Update VM configuration



# Create a new VPC
Source: https://developers.onidel.com/api-reference/vpc/create-a-new-vpc

/api-reference/openapi.yaml post /network/vpcs
Create a new Virtual Private Cloud network



# Delete VPC
Source: https://developers.onidel.com/api-reference/vpc/delete-vpc

/api-reference/openapi.yaml delete /network/vpcs/{vpc_id}
Delete a VPC (must not have any attached VMs)



# Get VPC by ID
Source: https://developers.onidel.com/api-reference/vpc/get-vpc-by-id

/api-reference/openapi.yaml get /network/vpcs/{vpc_id}
Retrieve a specific VPC by its UUID



# List VPCs
Source: https://developers.onidel.com/api-reference/vpc/list-vpcs

/api-reference/openapi.yaml get /network/vpcs
Retrieve all VPCs for a team



# Update VPC
Source: https://developers.onidel.com/api-reference/vpc/update-vpc

/api-reference/openapi.yaml patch /network/vpcs/{vpc_id}
Update an existing VPC's name, description, or shared teams