Welcome to the deSEC DNS API

The deSEC DNS API is a REST interface that allows easy management of DNS information. The interface design aims for simplicity so that tasks such as creating domains and manipulating DNS records can be handled with ease and in an intuitive fashion.

Server-side operations, such as creation of domains or DNS records, generally expect JSON-formatted user input in the body of the POST, PATCH, or PUT request (see below). Unless otherwise documented, requests are expected to come with a Content-Type: application/json header field and to be sent via HTTPS using state-of-the-art encryption. (Outdated setups, e.g. TLS < 1.2, are not supported.)

API functionality is demonstrated using the command line tool curl. To pretty-print JSON output, process the data through jq: curl ... | jq ..

Windows users: We are told that the curl commands in this documentation sometimes do not work. In this case, try moving the request payload in front of the curl call, like this:

echo {"name": "example.com"} | curl -X POST https://desec.io/api/v1/domains/ --header "Authorization: Token {secret}" --header "Content-Type: application/json" --data @-

User Management

• Quickstart
• Manage Account
  • Obtain a Captcha
  • Register Account
  • Log In
  • 2-Factor Authentication
  • Retrieve Account Information
  • Modify Account Settings
  • Password Reset
  • Password Change
  • Change Email Address
  • Delete Account
  • Log Out
  • Security Considerations
• Manage Tokens
  • Token Field Reference
  • Creating a Token
  • Modifying a Token
  • Listing Tokens
  • Retrieving a Specific Token
  • Deleting a Token
  • Token Scoping: Policies
  • Security Considerations

DNS Management

• Domain Management
  • Domain Field Reference
  • Creating a Domain
  • Listing Domains
  • Retrieving a Specific Domain
  • Identifying the Responsible Domain for a DNS Name
  • Exporting a Domain as Zonefile
  • Deleting a Domain
• Retrieving and Creating DNS Records
  • RRset Field Reference
  • Creating an RRset
  • Retrieving all RRsets in a Zone
  • Retrieving a Specific RRset
  • Modifying an RRset
  • Deleting an RRset
  • Bulk Operations
  • Record Types

dynDNS

• Configuring your dynDNS Client
  • Option 1: Use Your Router
  • Option 2: Use ddclient
  • Updating multiple domains
• IP Update API
  • Update Request
  • Update Response
  • Examples

Integrations

• TLS Certificates with Let’s Encrypt
  • certbot with deSEC Plugin
  • Other ACME Clients

API Summary

• Endpoint Reference
• Rate Limits
  • API Request Throttling
  • Throttling of Other Requests
• API Versions and Lifecycle

Getting Help

If you need help beyond this documentation, please do not hesitate and shoot us an email at support@desec.io.

About this document

To add to our documentation or fix a mistake, please submit a Pull Request at https://github.com/desec-io/desec-stack.