Change alias

Change an alias. The hostname and the CDN resource of an alias cannot be changed; delete the alias and create a new one instead.

Set active to false to stop serving the alias; certificate issuance stops, though an attempt already being processed completes. Set it back to true to resume. Resuming an alias without a valid Let’s Encrypt certificate starts a new issuance attempt, which is rate-limited, so it cannot be combined with automated in one request. A renewal stopped by the pause is started again by the scheduled renewal after the alias is resumed.

For an alias with your own certificate, pass a new certificate ID in ssl_id to replace it. The new certificate must cover the alias hostname.

Pass automated to switch how the certificate is managed. Switching to your own certificate takes effect at once and the Let’s Encrypt certificate issued for the alias is removed. Switching to a Let’s Encrypt certificate starts an issuance attempt while your certificate keeps being served, and the alias starts serving the new certificate once it is issued; if the attempt fails, ssl_status becomes failed and your certificate keeps being served. The certificate mode cannot be changed while the alias is paused — resume it first.

Pass challenge_type to change how the Let’s Encrypt certificate’s domain is validated. It cannot be changed while the alias is paused, or together with active. While no valid certificate is served, the change cancels the running issuance attempt and starts a new one; this is rate-limited like resuming, and is refused while that attempt is being processed. Otherwise the new method is used from the next attempt.

PATCH /cdn/aliases/{alias_id}

Python

Python

import os
from gcore import Gcore

client = Gcore(
    api_key=os.environ.get("GCORE_API_KEY"),  # This is the default and can be omitted
)
alias_detail = client.cdn.aliases.update(
    alias_id=0,
)
print(alias_detail)

200

{
  "id": 123,
  "cname": "shop.example.com",
  "resource_id": 4567,
  "automated": true,
  "challenge_type": "http_01",
  "ssl_id": 890,
  "active": true,
  "enabled": true,
  "status": "active",
  "ssl_status": "issued",
  "ssl_validity_not_after": "2027-01-01T10:00:00Z",
  "created": "2026-09-01T10:00:00Z",
  "updated": "2026-09-01T10:05:00Z",
  "ssl_provisioning": {
    "acme_delegation": {
      "cname_name": "_acme-challenge.shop.example.com",
      "cname_target": "0a1b2c3d4e5f6789.le-challenges.example.net"
    },
    "http_validation": {
      "cname_name": "shop.example.com",
      "cname_target": "cl-1a2b3c.cdn.example.net"
    }
  }
}

This endpoint is in beta. BETA

Authorizations

Authorization · string · header · required

API key for authentication. Make sure to include the word apikey, followed by a single space and then your token. Example: apikey 1234_abcdef

Path Parameters

alias_id · integer · required

Alias ID.

Body

application/json

active · boolean

Whether the alias is enabled.

Possible values:

• true – The alias is enabled.
• false – The alias is paused and is not served. Certificate issuance stops, though an attempt already being processed completes.

Example:

false

automated · boolean

How the alias certificate is managed. Change it to switch the alias between a Let's Encrypt certificate and your own. Cannot be changed while the alias is paused.

Possible values:

• true – Switch to a Let's Encrypt certificate. ssl_id must be omitted. The current certificate keeps being served until the new one is issued.
• false – Switch to your own certificate. ssl_id is required and is served immediately.

Example:

true

challenge_type · enum<string>

Domain validation method used to issue the Let's Encrypt certificate. Available for an alias with automated set to true, and together with automated set to true to switch to a Let's Encrypt certificate. Cannot be changed while the alias is paused, or together with active.

While no valid certificate is served, the running issuance attempt is cancelled and a new one is started with the new method. Otherwise the new method is used from the next attempt.

Available options: dns_01, http_01

Example:

"http_01"

ssl_id · integer

ID of your own SSL certificate to serve for the alias instead of the current one. The certificate must cover the alias hostname; a Let's Encrypt certificate issued for one of your CDN resources cannot be used. Available for an alias with automated set to false, and together with automated set to false to switch to your own certificate.

Example:

891

Response

200

application/json

Successful.

id · integer

Alias ID.

Example:

123

cname · string

Alias hostname. Cannot be changed after creation.

Example:

"shop.example.com"

resource_id · integer

ID of the CDN resource whose settings the alias is served with. Cannot be changed after creation.

Example:

4567

automated · boolean

How the alias certificate is managed. Can be changed while the alias is served.

Possible values:

• true – A Let's Encrypt certificate is issued and renewed automatically.
• false – The certificate referenced by ssl_id, if any, was added by you.

Example:

true

challenge_type · enum<string> | null

Domain validation method used to issue the Let's Encrypt certificate for the alias. null when automated is false.

Available options: dns_01, http_01

Example:

"http_01"

ssl_id · integer | null

ID of the SSL certificate served for the alias.

Example:

890

active · boolean

Whether you have enabled the alias.

Possible values:

• true – The alias is enabled.
• false – The alias is paused and is not served.

Example:

true

enabled · boolean

Whether the alias is enabled by the system. Follows the state of the CDN resource.

Possible values:

• true – The alias can be served.
• false – The alias is not served because its CDN resource is not active.

Example:

true

status · enum<string>

Alias status.

Possible values:

• inactive – The alias or its CDN resource is disabled; the alias is not served.
• pending – The alias configuration has not reached the CDN yet.
• http_only – The alias is served over HTTP only.
• active – The alias is served over HTTP and HTTPS.

Available options: inactive, pending, http_only, active

Example:

"active"

ssl_status · enum<string> | null

Outcome of the certificate we manage for the alias.

Possible values:

• pending – A certificate attempt is in progress, or was stopped by pausing the alias and starts again after it is resumed.
• issued – The latest attempt succeeded.
• failed – The latest attempt ended without a certificate.
• null – No certificate is managed for the alias: the alias uses a certificate you provided, or is automated and has never opened an attempt.

Available options: pending, issued, failed

Example:

"issued"

ssl_validity_not_after · string | null

Date and time when the served certificate expires (ISO 8601/RFC 3339 format, UTC). null while no certificate is served.

Example:

"2027-01-01T10:00:00Z"

created · string

Date and time when the alias was created (ISO 8601/RFC 3339 format, UTC).

Example:

"2026-09-01T10:00:00Z"

updated · string

Date and time when the alias was last changed (ISO 8601/RFC 3339 format, UTC).

Example:

"2026-09-01T10:05:00Z"

ssl_provisioning · object | null

DNS record needed for Let's Encrypt domain validation of the alias hostname. It is null when automated is false, and when challenge_type is dns_01 until a delegation record has been prepared for the hostname.

Show child attributes