API V1 RESOURCES LINKS

Domains

The domains represent the custom domain names defined for your applications. For instance, the alias www.example.com of example-app.scalingo.io will result in the presence of one resource domain.

Keys attributes

field type description
id string unique ID of the domain
name string hostname your want to associate with the app
tlscert (read) string subject of the submitted certificate
tlscert (write) string content of the SSL certificate you want to use
tlskey (read) string private key type and length
tlskey (write) string content of the private key used to generate the certificate
ssl (read-only) boolean flag if SSL with a custom certificate is enabled
validity (read-only) datetime once a certificate has been submitted, display the validity of it
ssl_status (read-only) string SSL certificate status (pending, success, error)
canonical boolean the domain is the canonical domain of this application
letsencrypt_enabled boolean automatic Let’s Encrypt certificate generation status
letsencrypt boolean the domain is currently using a Let’s Encrypt certificate
letsencrypt_status string Let’s Encrypt certificate generation status
acme_dns_fqdn string ACME DNS-01 TXT entry FQDN
acme_dns_value string ACME DNS-01 TXT entry value
acme_dns_error string ACME DNS-01 error

The letsencrypt_status field can take different values depending on your certificate state:

  • pending_dns: Scalingo is waiting for your DNS configuration to be correct
  • new: The certificate request has been sent to Let’s Encrypt
  • created: The certificate has been created by Let’s Encrypt and is available
  • dns_required: (wildcard only) Scalingo is waiting for DNS configuration update
  • error: There was an error while creating your certificate

Example object

{
  "id": "541067ec736f7504a5110000",
  "name": "example.com",
  "ssl": true,
  "tlscert": "/C=FR/ST=Some-State/O=Internet Widgits Pty Ltd/CN=example.com",
  "tlskey": "RSA private key - 2048 bytes",
  "validity": "2015-08-05T19:57:21.000+02:00",
  "canonical": false,
  "letsencrypt_enabled": true,
  "letsencrypt": false,
  "letsencrypt_status": "created"
}

List all the domains of an application

GET https://$SCALINGO_API_URL/v1/apps/[:app]/domains

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
 -H "Authorization: Bearer $BEARER_TOKEN" \
 -X GET https://$SCALINGO_API_URL/v1/apps/example-app/domains

Returns 200 OK

{
    "domains": [
        {
            "id": "541067f7736f7504a5140000",
            "name": "example2.com",
            "ssl": false,
            "canonical": true,
            "letsencrypt_enabled": true,
            "letsencrypt": false,
            "letsencrypt_status": "pending"
        },
        {
            "id": "541067ec736f7504a5110000",
            "name": "example.com",
            "ssl": true,
            "tlscert": "/C=FR/ST=Some-State/O=Internet Widgits Pty Ltd/CN=example.com",
            "tlskey": "RSA private key - 2048 bytes",
            "validity": "2015-08-05T19:57:21.000+02:00",
            "canonical": false,
            "letsencrypt_enabled": true,
            "letsencrypt": false,
            "letsencrypt_status": "created"
        }
    ]
}

Show a specific domain of an application

GET https://$SCALINGO_API_URL/v1/apps/[:app]/domains/[:domain_id]

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
 -H "Authorization: Bearer $BEARER_TOKEN" \
 -X GET https://$SCALINGO_API_URL/v1/apps/example-app/domains/541067ec736f7504a5110000

Returns 200 OK

{
    "domain": {
        "id": "541067ec736f7504a5110000",
        "name": "example.com",
        "ssl": false,
        "canonical": false,
        "letsencrypt_enabled": true,
        "letsencrypt": false,
        "letsencrypt_status": "new"
    }
}

DELETE https://$SCALINGO_API_URL/v1/apps/[:app]/domains/[:domain_id]

Disassociate instantly a domain name with an app. If the domain is still CNAME-ed, it will respond with a 404 error.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X DELETE https://$SCALINGO_API_URL/v1/apps/example-app/domains/541067ec736f7504a5110000

Returns 204 No Content

POST https://$SCALINGO_API_URL/v1/apps/[:app]/domains

Parameters

  • domain.name: Hostname you want to add
  • domain.tlscert - optional: SSL Certificate you want to associate with the domain
  • domain.tlskey - optional: Private key used to create the SSL certificate
  • domain.canonical - optional: Set this domain as the canonical domain for this application
  • domain.letsencrypt_enabled - optional (true by default): Enable automatic certificate generation with Let’s Encrypt

If the certificate or the key is not valid, a 422 “unprocessable entity” is returned Otherwise return 201

Limit

There is a hard limit of 20 custom domains per application, if you need more: contact us

Request example (without SSL):

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps/example-app/domains -d \
  '{
    "domain" : {
      "name" : "example.com"
    }
  }'

Returns 201 Created

{
    "domain": {
        "id": "541067ec736f7504a5110000",
        "name": "example.com",
        "ssl": false,
        "canonical": false,
        "letsencrypt_enabled": true,
        "letsencrypt": false,
        "letsencrypt_status": "new"
    }
}

Request example (with SSL):

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps/example-app/domains -d \
  '{
    "domain" : {
      "name" : "example.com",
      "tlscert" : "<cert>",
      "tlskey" : "<key>"
     }
   }'

Returns 201 Created

{
    "domain": {
        "id": "541067ec736f7504a5110000",
        "name": "example.com",
        "ssl": true,
        "tlscert": "/C=FR/ST=Some-State/O=Internet Widgits Pty Ltd/CN=example.com",
        "tlskey": "RSA private key - 2048 bytes",
        "validity": "2015-08-05T19:57:21.000+02:00",
        "canonical": false,
        "letsencrypt_enabled": true,
        "letsencrypt": false,
        "letsencrypt_status": "new"
    }
}

Update a domain name

PATCH https://$SCALINGO_API_URL/v1/apps/[:app]/domains/[:domain_id]

Parameters

  • domain.tlscert - optional: SSL Certificate you want to associate with the domain
  • domain.tlskey - optional: Private key used to create the SSL certificate
  • domain.canonical - optional: Set this domain as the canonical domain for this application
  • domain.letsencrypt_enabled - optional (true by default): Enable automatic certificate generation with Let’s Encrypt

As you may have noticed you can’t update the name itself, instead of modifying it just create another Domain and delete the one you wanted to modify.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X PATCH https://$SCALINGO_API_URL/v1/apps/example-app/domains/541067ec736f7504a5110000 -d \
  '{
    "domain" : {
      "tlscert" : "<cert>",
      "tlskey" : "<key>"
    }
  }'

Returns 200 OK

{
    "domain": {
        "id": "541067ec736f7504a5110000",
        "name": "example.com",
        "ssl": true,
        "tlscert": "/C=FR/ST=Some-State/O=Internet Widgits Pty Ltd/CN=example.com",
        "tlskey": "RSA private key - 2048 bytes",
        "validity": "2015-08-05T19:57:21.000+02:00",
        "canonical": false,
        "letsencrypt_enabled": true,
        "letsencrypt": false,
        "letsencrypt_status": "new"
    }
}