nsindocs Search the docs⌘K
API
  1. Docs
  2. API reference
  3. SSL

Store acme-dns credentials for this domain

puthttps://api.nsin.ir/domains/{domain}/ssl/acme-dns

Auth: Authorization: Bearer nsin_… or X-Api-Key: nsin_… — see API keys.

Lets NSIN issue and renew certificates for a domain whose DNS is somewhere we cannot write, by writing DNS-01 challenge values through an acme-dns instance you already delegate _acme-challenge to. Nothing in your own DNS has to change.

Send the contents of your acmedns.json in credentials, as a string — the whole file, quoting and all if you lifted it out of a compose file. A single pasted account object is also accepted.

A file covering several domains is normal, and only the entry for this domain is stored. If it has no entry for this domain the request is refused with code: "domain_not_covered" and covered lists the domains it is actually for.

The credentials are then checked for real, by writing a throwaway value through the API — acme-dns has no other way to test an account. A failure is refused with code: "verification_failed"; pass force: true to store them anyway when you know the instance is merely unreachable. Requires ssl.manage and a plan that includes custom certificates.

Path parameters

  • domainstringrequiredpath

    The domain name (for example example.com) — not a numeric id.

Request body

Content type: application/json · required

  • credentialsstringrequired

    The contents of acmedns.json.

  • forceboolean

    Store the account even if the live check fails.

Responses

200Stored.

Content type: application/json

  • messagestring
  • acme_dnsAcmeDnsAccount

    A domain's acme-dns account. The password is never returned.

    Fields
    • configuredboolean

      False, and nothing else set, when this domain has no account.

    • domainstring

      The domain this account was accepted for.

    • api_basestring

      The acme-dns instance challenge values are written to, derived from the account's own fulldomain.

    • usernamestring
    • full_domainstring

      The name inside acme-dns that holds this domain's challenge values.

    • allow_fromstring

      The account's IP allowlist as acme-dns reported it. Empty means the account may be used from any address; that is fixed at registration and cannot be changed from here.

    • cname_namestring

      The record that must exist in your own DNS.

    • cname_targetstring
    • updated_atstring (date-time)
json
{
  "message": "string",
  "acme_dns": {
    "configured": true,
    "domain": "string",
    "api_base": "string",
    "username": "string",
    "full_domain": "string",
    "allow_from": "string",
    "cname_name": "_acme-challenge.numberland.ir",
    "cname_target": "e940716e-147b-477c-80a1-3cff2e2fbccf.auth.acme-dns.io.",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}
400Unreadable credentials, an entry missing a required field, a file with no entry for this domain (code: "domain_not_covered"), or credentials that did not work (code: "verification_failed").

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

  • codestring
    One of: "domain_not_covered" "verification_failed"
  • coveredarray of string

    The domains the uploaded file does cover.

json
{
  "error": "string",
  "code": "domain_not_covered",
  "covered": [
    "string"
  ]
}
401Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "invalid API key"
}
402The domain has no active plan.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
403Read-only key, insufficient role, or the plan does not include custom certificates.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
404No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
429The key exceeded its request budget (300 requests per minute by default).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "rate limit exceeded"
}

Example request

bash
curl -X PUT "https://api.nsin.ir/domains/example.com/ssl/acme-dns" \
  -H "Authorization: Bearer $NSIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credentials": "string",
  "force": true
}'
esc