English | Deutsch | Español | Português
 UserID:
 Passwd:
new user
 About  | API Guide  | API Key  | JavaScript Example | PHP CLI Example
 
REST API Guide

Table of Contents

APIs
Authentication (auth.php)
Security Audits: Get Audit List (saGetAuditList.php)
Security Audits: Get Audit Report (saGetAuditReport.php)
Security Audits: Run Audit (saRunAudit.php)
DNS: Get Domain List (dnsGetDomainList.php)
DNS: Get Domain (dnsGetDomainRecords.php)
DNS: Add Domain (dnsAddDomain.php)
DNS: Delete Domain (dnsDeleteDomain.php)
DNS: Delete Record (dnsDeleteRecord.php)
DNS: Add A Record (dnsAddA.php)
DNS: Add AAAA Record (dnsAddAAAA.php)
DNS: Add CNAME Record (dnsAddCNAME.php)
DNS: Add MX Record (dnsAddMX.php)
DNS: Add NS Record (dnsAddNS.php)
DNS: Add CAA Record (dnsAddCAA.php)
DNS: Add TXT Record (dnsAddTXT.php)
DNS: Add SRV Record (dnsAddSRV.php)
DNS: Set SOA Record values (dnsSetSOA.php)
DNS: Set Options (dnsSetOptions.php)
DNS: Validate and Publish Zone (dnsPublish.php)
DNS: Build Zone File (dnsBuildZone.php)

Introduction

Technology
HTTP Service calls
Access to security space API services is done exclusively over HTTP POST requests, running over an SSL protocol. Responses are received in JSON. A sample transaction is shown below.

HTTP Request
POST /api/auth.php HTTP/1.0
Host: secure1.securityspace.com
Content-Length: 78
Content-type: application/x-www-form-urlencoded

apikey=WjN5ZkVoWm9KS2FvaHVGbE5VQ2loeHdP&userid=youruseridpassword=yourpassword

HTTP Response
HTTP/1.1 200 OK
Date: Mon, 17 Nov 2014 22:07:24 GMT
Server: Apache
X-Powered-By: PHP/5.4.4-14+deb7u14
Cache-Control: no-cache, must-revalidate
Expires: Mon, 17 Nov 2014 17:07:24 EST
Content-Length: 814
Connection: close
Content-Type: application/json

{ "status": "0", "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"}

JSON (JavaScript Object Notation) Data Format
APIs return information in JSON. JSON's advantages are:
  1. Low overhead (efficient data transfer)
  2. Human readable
  3. Support in a large number of languages (check here)

An example of a JSON data response would be
{
    "status": "0",
    "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"
}

API Error Indicators

All responses to SecuritySpace APIs will contain a "status" field, which will have a value of "0" if the request was successful, or a non-zero value on error. When there is an error, a static error response will be returned consisting of the status field and an "error" field, with the error field containing an error message indicating the reason for the failure.

An example of a successful JSON data response would be
{
    "status": "0",
    "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"
}

An example of an error response is:
{
    "status": "-1",
    "error": "invalidLogin"
}

APIs

Authentication (auth.php)
DescriptionAuthenticate to your SecuritySpace account and get back a session token that can be used in all APIs accessing/manipulating your account information. Returned tokens are valid for 24 hours, after which they expire and a new token must be requested.
URLhttps://secure1.securityspace.com/api/auth.php
PrerequisitesValid API key, active account
InputapikeyYour SecuritySpace api key
useridYour SecuritySpace account userid
passwordYour SecuritySpace account password
Success
Response
Schema
{
    "required": true,
    "type": "object" ,
    "properties": {
	"status" : { "required": true, "type": "number" },
	"sessionToken" : { "required": true, "type": "string" }
    } 
} 
ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
missing credentialsInput parameters missing userid and/or password
invalidLoginLogin incorrect - wronger userid/password combination
sysErrEntitlementLoadSystem Error - unable to load account entitlements
tokenCreationSystem Error - unable to create token
sysErrdoLoginSystem Error - unspecified error returned from authentication request

Security Audit - Get Audit List (saGetAuditList.php)
DescriptionRetrieve the list of audit reports in your account, along with some basic audit information
URLhttps://secure1.securityspace.com/api/saGetAuditList.php
PrerequisitesValid API key, valid session token
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	"scancount" : { "required": true, "type": "number" },
	"scans" : {
	    "required": false,
	    "type": "array" ,
	    "items": {
		"required": true,
		"type": "object" ,
		"properties": {
		    "scanuid" : { "required": true, "type": "string" },
		    "folder" : { "required": true, "type": "string" },
		    "hostip" : { "required": true, "type": "string" },
		    "time_end" : { "required": true, "type": "string" },
		    "time_queued" : { "required": true, "type": "string" },
		    "time_start" : { "required": true, "type": "string" },
		    "type" : { "required": true, "type": "string" }
		} 
	    }
	}
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid

Security Audit - Get Audit Report (saGetAuditReport.php)
DescriptionRetrieve the specified audit report
URLhttps://secure1.securityspace.com/api/saGetAuditReport.php
PrerequisitesValid API key, valid session token
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
scanuidA valid scan identifier
Success
Response
Schema

{
  "required": true,
  "type": "object" ,
  "properties": {
    "status" : { "required": true, "type": "number" },
    "scaninfo" : {
      "required": true,
      "type": "object" ,
      "properties": {
	"basic" : {
	  "required": true,
	  "type": "object" ,
	  "properties": {
	      "detail_supplement" : { "required": true, "type": "number" },
	      "ejtime" : { "required": true, "type": "string" },
	      "hostip" : { "required": true, "type": "string" },
	      "merge" : { "required": true, "type": "number" },
	      "mergelist" : { "required": true, "type": "string" },
	      "promocode" : { "required": true, "type": "string" },
	      "qjtime" : { "required": true, "type": "number" },
	      "reporttype" : { "required": true, "type": "string" },
	      "scanattr" : { "required": true, "type": "string" },
	      "scanportstcp" : { "required": true, "type": "string" },
	      "scantype" : { "required": true, "type": "string" },
	      "scanuid" : { "required": true, "type": "number" },
	      "sjtime" : { "required": true, "type": "number" },
	      "title" : { "required": true, "type": "string" },
	      "totalnaslentries" : { "required": true, "type": "number" }
	  } 
	},
	"entries" : {
	  "required": false,
	  "type": "object" ,
	  "properties": {
	    "<high|medium|low|other>" : { //test results organized by risk groups
	      "required": false,
	      "type": "object" ,
	      "properties": {
		"<scanuid_sequence#>" : {// E.g. Property name of 1100005104_58
		  "required": true,
		  "type": "object" ,
		  "properties": {
		    // Which report this came from (required for merged view)
		    "repid" : { "required": true, "type": "string" },
		    // The test ID (full ID)
		    "id" : { "required": true, "type": "string" },
		    // The short form test ID
		    "shortid" : { "required": true, "type": "string" },
		    // IP address of the host
		    "ip" : { "required": true, "type": "string" },
		    // Port# on which this is applicable
		    "port" : { "required": true, "type": "string" },
		    // Category of this test
		    "cat" : { "required": true, "type": "string" },
		    // Any CVE identifiers (CSV)
		    "cve" : { "required": true, "type": "string" },
		    // The unique entry key (e.g. 1100005104_58)
		    "entrykey" : { "required": true, "type": "string" },
		    // The risk level (one of high,medium,low,other)
		    "risk" : { "required": true, "type": "string" },
		    // The short entry key (sequence # - e.g. 58)
		    "shortkey" : { "required": true, "type": "number" },
		    // The static test description
		    "static_description" : { "required": true, "type": "string" },
		    // The full test description, including dynamically
		    // generated elements
		    "description" : { "required": true, "type": "string" },
		    "title" : { "required": true, "type": "string" },
		    // Type of test entry report (LOG,NOTE,HOLE)
		    "type" : { "required": true, "type": "string" }
		    // Baseline assessment results
		    "baseline" : { "required": true, "type": "string" },
		  } 
		}
	      } 
	    }
	  } 
	},
	"ports" : { // Report the open ports that were found.
	  "required": true,
	  "type": "array" ,
	  "items": {
	    "required": true,
	    "type": "object" ,
	    "properties": {
	      // Which report this item belonged to (useful only for merged views)
	      "repid" : { "required": true, "type": "string" }
	      "hostip" : { "required": true, "type": "string" },
	      // first port in range
	      "portend" : { "required": true, "type": "number" },
	      // last port in range, -1 if not a range
	      "portnum" : { "required": true, "type": "string" },
	      // Protocol (TCP/UDP)
	      "portprot" : { "required": true, "type": "string" },
	      // Name of service typically residing on this port
	      "portservice" : { "required": true, "type": "string" },
	    } 
	  }
	},
	"risk" : { // The number of vulnerabilities at each risk level
	  "required": true,
	  "type": "object" ,
	  "properties": {
	    "high" : { "required": false, "type": "number" },
	    "low" : { "required": false, "type": "number" },
	    "medium" : { "required": false, "type": "number" },
	    "other" : { "required": false, "type": "number" }
	  } 
	},
	"riskcatgrid" : {
	  "required": true,
	  "type": "object" ,
	  "properties": {
	    // Multiple entries, with property name consisting of the
	    // the test category:risk level. E.g. "RPC:other"
	    "<category:risk>" : { "required": false, "type": "number" },
	  }
	}
      }
    }
  }
} 

ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
reportLoadFailure[<code>]report failed to load

Security Audit - Run Audit (saRunAudit.php)
DescriptionRun a security audit against an IP address or a range of addresses.
URLhttps://secure1.securityspace.com/api/saRunAudit.php
PrerequisitesValid API key, active account
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
ipaddrOptional:IP address(es) of the host(s) to be audited. Wild cards (*) and hyphens for ranges may be employed on any portion of an IP address, and multiple comma separated values may be specified. E.g. "192.168.1.*,10.1.1-2.32-63" would request an audit of all 256 addreesses in the 192.168.1.0/24 range, as well as another 2 /27 ranges of 10.1.1.32/27 and 10.1.2.32/27. If not specified, will default to the detected IP address of the client making the request.
audittypeMust be specified as one of { advanced, standard, norisk, desktop, basic }
excludedosOptional:If set (to any value), the audit will exclude tests in the denial of service category. Otherwise, all tests will be run.
notificationOptional:Set to OCMP to receive an on completion notification email that the audit has finished running. Defaults to not sending any notification.
Success
Response
Schema
{
    "required": true,
    "type": "object" ,
    "properties": {
	"status" : { "required": true, "type": "number" },
    } 
} 
ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
missingAuditTypeThe audit type was not specified.
invalidAuditTypeAn invalid audit type was specified
IPPermissionsProblemUser doesn't have permissions on this account to audit one or more addresses in the audit request. Full request has been rejected.
missingScanClientsRecAn internal system error.
notEntitledA request was made to run an audit for which the user has not subscribed.
noriskAlreadyRunA limit of one no risk audit per IP address per month is enforced. This is a second request, and has been rejected.

DNS: Get Domain List (dnsGetDomainList.php)
DescriptionRetrieve the list of domains managed in your account
URLhttps://secure1.securityspace.com/api/dnsGetDomainList.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	// Number of domains in this account
	"domaincount" : { "required": true, "type": "number" },
	// Total "credit" weight of all domains
	"domainweight" :  { "required": true, "type": "number" },
	// subscription expiry julian timestamp (seconds since 1970)
	"expiryjtime" :  { "required": true, "type": "number" },
	// subscription expiry human readable
	"expiryreadable" :  { "required": true, "type": "string" },
	"domains" : {
	    "required": false,
	    "type": "object" ,
	    "properties": {
		// A unique sequence number for this domain.
		: {
		    "required": true,
		    "type": "object" ,
		    "properties": {
			// The domain name.
			"domain" : { "required": true, "type": "string" },
			// The unique sequence number of this domain (same as above sequence number)
			"seq" : { "required": true, "type": "number" },
			// The credit weight of the domain (1 without any web forwarding, 2 with web forwarding)
			"weight" : { "required": true, "type": "number" },
			// The state of the domain.
			// state 0: "Unvalidated"
			// state 1: "Configuration Errors"
			// state 2: "Waiting for distribution to name servers"
			// state 3: "Active"
			"state" : { "required": true, "type": "number" },
			"stateText" : { "required": true, "type": "string" },
		    } 
		}
	    }
	}
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
dnsDomainRetrievalFailureA system error occurred retrieving your domain information. Try again later

DNS: Get Domain Records (dnsGetDomainRecords.php)
DescriptionRetrieve all records associated with a domain
URLhttps://secure1.securityspace.com/api/dnsGetDomainRecords.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain name
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	"domain" : { "required": true, "type": "string" },
	// The state of the domain.
	// state 0: "Unvalidated"
	// state 1: "Configuration Errors"
	// state 2: "Waiting for distribution to name servers"
	// state 3: "Active"
	"state" : { "required": true, "type": "number" },
	"stateText" : { "required": true, "type": "string" },

	"records" : {
	    "required": true,
	    "type": "object" ,
	    "properties": {
		// A unique sequence number for this record. Deletion requests must provide this seq #
		<seq>: {
		    "required": true,
		    "type": "object" ,
		    "properties": {
			// The record type. Possible values:  SOA, NS, MX A, AAAA, CNAME, TXT, SRV, Options, WebForwarding
			"seq" : { "required": true, "type": "string" }, // unique record identifier
			"type" : { "required": true, "type": "string" },
			// The unique sequence number of this domain (same as above sequence number)
			"data" : {
			    "required": true,
			    "type": "object" ,
			    "properties": {
				// Values returned are dependent on the type as follows:
				// NS/A/AAAA/CNAME/TXT values:
				"name" : { "required": true, "type": "string" },
				"data" : { "required": true, "type": "string" }

				// MX values
				"pri" : { "required": true, "type": "number" }, //priority
				"host" : { "required": true, "type": "string" }, // aka subdomain, usually blank
				"data" : { "required": true, "type": "string" } // the mail server name

				// CAA values
				"name" : { "required": true, "type": "string" }, // aka subdomain, usually blank
				"flag" : { "required": true, "type": "number" }, // CAA flag value
				"tag" : { "required": true, "type": "string" } // CAA tag (one of issue, issuewild, iodef)
				"caaval" : { "required": true, "type": "string" } // the issuer value

				// SOA values
				"priNS" : { "required": true, "type": "string" },
				"mail" : { "required": true, "type": "string" }, //admin contact
				"refresh" : { "required": true, "type": "number" },
				"retry" : { "required": true, "type": "number" },
				"exp" : { "required": true, "type": "number" },
				"min" : { "required": true, "type": "number" } // minTTL

				// SRV values
				"srvc" : { "required": true, "type": "string" },
				"prot" : { "required": true, "type": "string" },
				"host" : { "required": true, "type": "string" },
				"pri" : { "required": true, "type": "number" },
				"weight" : { "required": true, "type": "number" },
				"port" : { "required": true, "type": "number" },
				"target" : { "required": true, "type": "string" }

				// Option values
				// See https://secure1.securityspace.com/dns/help-allowtransfer.html
				"allowtransferacl" : { "required": true, "type": "string" },
				// See https://secure1.securityspace.com/dns/help-notify.html
				"notify" : { "required": true, "type": "string" }
				// See https://secure1.securityspace.com/dns/help-alsonotify.html
				"alsonotify" : { "required": true, "type": "string" }

				// WebForwarding values
				"host" : { "required": true, "type": "string" },
				"target" : { "required": true, "type": "string" },
				"cloak" : { "required": true, "type": "number" }

			    }
			}
		    } 
		}
	    }
	}
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
dnsDomainRetrievalFailureA system error occurred retrieving your domain information. Try again later
noSuchDomainThe requested domain does not exist in your account.

DNS: Add Domain (dnsAddDomain.php)
DescriptionAdd a domain to your account. When a domain is added, a default set of NS records are added, along with a default SOA record. The NS records point to ns1 through ns4 (.securityspace.net), and the SOA record notably has a minTTL value of 1 day (86400 seconds). The domain is left in the "Unvalidated" state - it does not get moved to name servers until you publish the domain.
URLhttps://secure1.securityspace.com/api/dnsAddDomain.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain name to add
domaintypeThe type of domain (must be either 'master' or 'slave')
aupThe Acceptable Use Policy (AUP) is accepted (must pass a value of 'YES'; see the DNS AUP)
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
mustAcceptAUPThe AUP was not accepted. Accept the AUP by passing an 'aup' value of "YES" via the request
syntaxInvalidDomainThe domain provided is not a valid domain name
syntaxInvalidDomainTypeThe domain provided is not valid. Must be 'master' or 'slave'
unableToAddSystemA system error occurred trying to add the domain.
unspecifiedErrorAn unspecified system error occurred trying to add the domain.
unableToAddDuplicateThe domain could not be added - it appears to already be in this account.

DNS: Delete Domain (dnsDeleteDomain.php)
DescriptionDelete a domain from your account. Once a domain deletion request is successfully submitted, it cannot be undone. The deletion from name servers is queued up, and will be processed within 5 minutes. Until that time, name servers will continue to service DNS requests for the domain.
URLhttps://secure1.securityspace.com/api/dnsDeleteDomain.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain name to delete
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	// Number of domains left in this account
	"domaincount" : { "required": true, "type": "number" },
	// Total "credit" weight of all domains
	"domainweight" :  { "required": true, "type": "number" },
	// subscription expiry julian timestamp (seconds since 1970)
	"expiryjtime" :  { "required": true, "type": "number" },
	// subscription expiry human readable
	"expiryreadable" :  { "required": true, "type": "string" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not a valid domain name
domainNotDeletedThe domain was not deleted. Probably because the domain is not under this account.
unspecifiedErrorA system error occurred trying to delete the domain.

DNS: Delete Record (dnsDeleteRecord.php)
DescriptionDelete a DNS record from your a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsDeleteRecord.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
seqThe record sequence identifier
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidSeqThe sequence number provided is not valid
recordNotDeletedThe record was not deleted. Probable cause is an invalid sequence number.

DNS: Add A Record (dnsAddA.php)
DescriptionAdd an A record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddA.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
nameThe hostname. It may be blank (the base domain will resolve to an IP), a hostname, or an asterisk (wildcard - anything resolves to this IP unless otherwise explicitly specified).
ipThe IP address the hostname should resolve to.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidHostnameThe hostname is not valid.
syntaxInvalidIPThe IP address is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add AAAA Record (dnsAddAAAA.php)
DescriptionAdd an AAAA record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddAAAA.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
nameThe hostname. It may be blank (the base domain will resolve to an IP), a hostname, or an asterisk (wildcard - anything resolves to this IP unless otherwise explicitly specified).
ipThe IPv6 address the hostname should resolve to.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidHostnameThe hostname is not valid.
syntaxInvalidIPThe IP address is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add CNAME Record (dnsAddCNAME.php)
DescriptionAdd an CNAME record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddCNAME.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
aliasThe CNAME to be added
nameThe hostname that the CNAME resolves to.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidCNAMEThe CNAME is not valid.
syntaxInvalidHostnameThe hostname is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add MX Record (dnsAddMX.php)
DescriptionAdd an MX record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddMX.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
nameThe name to be added (typically blank, unless you wish to have the MX server handle a subdomain)
mxnameThe name of the mailserver (if in a different domain, it must be a fully qualified domain name ending with a ".".
priorityThe priority of this mailserver (numeric value from 0 to 99).
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidMXThe name/subdomain is not valid.
syntaxInvalidHostnameThe hostname is not valid.
noSuchDomainThe requested domain does not exist in your account.
syntaxInvalidPriorityAn invalid priority was passed in.
unspecifiedErrorThe record was not added.

DNS: Add CAA Record (dnsAddCAA.php)
DescriptionAdd a CAA record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddNS.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
subdomainThe subdomain for this CAA record (typically left blank)
flagThe flag value of the record.
tagThe tag value of the record (one of issue, issuewild, or iodef).
valueThe value field.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidSubdomainThe subdomain given is not valid.
syntaxInvalidFlagThe flag given is not valid (must be numeric 0-255).
syntaxInvalidTagThe tag given is not valid (must be numeric one if "issue", "issuewild" or "iodef").
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add NS Record (dnsAddNS.php)
DescriptionAdd an NS record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request. It should be noted that when you add a domain to SecuritySpace, the name servers are automatically populated for you. You should not need to add any, unless you want to have nameservers listed for subdomains of your domain.
URLhttps://secure1.securityspace.com/api/dnsAddNS.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
subdomainThe subdomain for this nameserver (normally left blank)
nameserverThe actual nameserver's fully qualified hostname.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidSubdomainThe subdomain given is not valid.
syntaxInvalidHostnameThe nameserver hostname is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add TXT Record (dnsAddTXT.php)
DescriptionAdd a TXT record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddTXT.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
nameThe txt data record name. If you are adding SPF records for your domain, this field would normally be left blank
txtdataThe actual nameserver's fully qualified hostname.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidTxtnameThe subdomain given is not valid.
syntaxInvalidTxtdataThe nameserver hostname is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Add SRV Record (dnsAddSRV.php)
DescriptionAdd a SRV record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request.
URLhttps://secure1.securityspace.com/api/dnsAddSRV.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
srvcThe srvc value
protThe protocol value
hostThe host value
priThe priority value
weightThe weight value
portThe port value
portThe port value
targetThe target
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidSrvcThe srvc value given is not valid.
syntaxInvalidProtThe protocol value given is not valid.
syntaxInvalidHostnameThe protocol value given is not valid.
syntaxInvalidTargetThe target value given is not valid.
syntaxInvalidPriorityThe priority value given is not valid.
syntaxInvalidWeightThe weight value given is not valid.
syntaxInvalidPortThe port value given is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Set SOA Record values (dnsSetSOA.php)
DescriptionAdd the admin contact (aka email) and TTL values for a domaina TXT record to a domain. Doing so will place the domain in an unvalidated state. It will stay in that state, until you issue a Publish request. When invoking this API, you can make change to either or both of the admin/ttl values. You must be passing at least one of those parameters in.
URLhttps://secure1.securityspace.com/api/dnsAddTXT.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain to which a record is added
adminOptional: The admin contact information. Note that it must be passed in as an email address (aaa@bbb.ccc) and gets translated to . notation (aaa.bbb.ccc).
ttlOptional: The minimum TTL value for your domain's records. Default value is 86400 (1 day), and should generally not be changed. One exception to this is when you know you are going to make IP address changes on your network (like moving a web server or mail server), then by setting the TTL value to something low in advance of the change, you can ensure that when you make the change, everyone picks up the new DNS records quickly. Once the change has been completed, you should set this value back up to the 1-2 day range.
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
missingInputNo input values detected (ttl/admin).
syntaxInvalidTTLThe TTL value provide is not valid.
syntaxInvalidAdminThe admin contact given is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Set Options (dnsSetOptions.php)
DescriptionAllows for setting of various option values.
URLhttps://secure1.securityspace.com/api/dnsAddTXT.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain for which the options are being modified
mastersFor slave domains, one or more IP addresses that are masters. See masters
allowtransferaclOptional:Control of zone transfers. See allowtransfer
notifyOptional:Notify slave servers of changes. See notify
alsonotifyOptional:Which slave servers receive notify messages. See alsonotify
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
syntaxInvalidMastersThe masters value provided is not valid.
syntaxInvalidAllowtransferaclThe allowtransferacl value provided is not valid.
syntaxInvalidNotifyThe notify value provided is not valid.
syntaxInvalidAlsoNotifyThe alsonotify value provided is not valid.
logicAlsoNotifyRequiresNotifyAlsonotify requires a notify parameter.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Publish a domain (dnsPublish.php)
DescriptionAnytime changes are made to a domain, the changes remain in the securityspace databases until all edits you want to make are complete. Once everything is done, you need to issue a "Publish" request in order to push the changes out to the nameservers. The action of publishing actually consists of two steps: A validation procedure that loads the domain into a test name server, and if that succeeds, a queue for distribution request. Note that new domains that are added to the system will be on hold, and the validation will fail until the hold is removed. Changes are distributed to name servers once every 5 minutes.

Note that the response schema is a bit different. The system may return a success status, but still return a series of warnings for the domain. Errors, if they are returned, indicate that the domain could not be published as is, and corrective action needs to be taken.

URLhttps://secure1.securityspace.com/api/dnsAddTXT.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain being validated and published
Success/Fail
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	"warnings" : { 
	    "required": false,
	    "type": "array" ,
	    "items": {
		"required": true,
		"type": "string" ,
	    }
	}
	"errors" : {
	    "required": false,
	    "type": "array" ,
	    "items": {
		"required": true,
		"type": "string" ,
	    }
	}
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.

DNS: Build Zone file (dnsBuildZone.php)
DescriptionThis returns what a new zone file would look like if you issue a "Publish" request. It is current with any changes made in the database, including those that have not yet been published.
URLhttps://secure1.securityspace.com/api/dnsBuildZone.php
PrerequisitesValid API key, valid session token, valid DNS subscription
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
domainThe domain for which the zone file is being built
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	"zone" :   { "required": true, "type": "string" },
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
dbConnectionFailureFailed to connect to the database
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
dnsEntitlementsOrCreditsMissingYour subscription has expired, or your credits have all been used up
syntaxInvalidDomainThe domain provided is not valid.
noSuchDomainThe requested domain does not exist in your account.
unspecifiedErrorThe record was not added.



Home | About Us | Contact Us | Partner Programs | Developer APIs | Privacy | Mailing Lists | Abuse
Security Audits | Managed DNS | Network Monitoring | Site Analyzer | Internet Research Reports
Web Probe | Whois

© 1998-2018 E-Soft Inc. All rights reserved.