Using the API

The IBM NS1 Connect API provides comprehensive tools for managing DNS resources, traffic steering configurations, and all aspects of your account. This REST API returns JSON responses and uses standard HTTP methods (GET, PUT, POST, DELETE) to perform operations on resources.

Refer to the API documentation for a full index of API endpoints and requests, as well as a growing library of developer guides to assist with API-specific workflows.

Base URLs

  • Legacy endpoints: https://api.nsone.net/v1
  • Newer endpoints: https://api.nsone.net/{category}/v1 (e.g., /alerting/v1, /apikeys/v1)

Key features

  • Manage DNS zones, records, and configurations
  • Configure traffic steering and filtering
  • Monitor account usage and analytics
  • Administer users, teams, and permissions

Authentication

The NS1 Connect API uses API key secrets to authenticate requests. The first API key you create must be done through the NS1 Connect portal, but then you can manage API keys and their corresponding secrets in the portal or using the API. This includes the ability to rotate key secrets before their expiration to avoid downtime.

Note: API keys can be configured with an expiry value that is inherited by all associated secrets and determines the amount of time a secret will remain valid until it expires. Optionally, you can choose not to apply an expiration, allowing the first associated secret to be valid indefinitely.

Include your API key in the X-NSONE-Key header with each request: X-NSONE-Key: $NSONE_API_KEYReplace $NSONE_API_KEY with a valid API key secret. Consider setting it as an environment variable for easier use in code examples.

Consider the following best practices:
  • Create separate API keys for different integrations or use cases.
  • Limit permissions to only what is required for the intended application or use.
  • Store API key secrets securely and never commit them to version control.
  • Rotate keys periodically.

Refer to API keys for details.

HTTP request methods

Note: All API requests must be made over HTTPS. Requests made over plain HTTP or without authentication will fail.

The HTTP method determines the type of action performed by the API. Most PUT and POST requests require a JSON body with resource details.

  • GET - Retrieves a representation of the specified resource.
  • PUT - Creates a new resource at the specified endpoint.
  • POST - Updates or modifies an existing resource.
  • DELETE - Removes the specified resource or configuration.
Note: For legacy endpoints, NS1 Connect uses PUT for creation and POST for updates, which is different from some REST conventions. This is consistent throughout legacy endpoints. Newer API endpoints may follow different conventions.