--- title: "Change alias" method: PATCH path: "/cdn/aliases/{alias_id}" tags: ["Aliases"] --- # Change alias `PATCH /cdn/aliases/{alias_id}` ## Request - Base URL: `https://api.gcore.com` - URL: `https://api.gcore.com/cdn/aliases/{alias_id}` - Auth: HTTP apikey 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. ## Path parameters - `alias_id` integer, required ## Request body - ChangeAlias - `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. - `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. - `challenge_type` 'dns_01' | 'http_01': Domain validation method used to issue the Let's Encrypt certificate for the alias. Possible values: - `dns_01` – Validation via a CNAME record for `_acme-challenge.`, shown in `ssl_provisioning.acme_delegation`. - `http_01` – Validation via an HTTP request to the alias hostname. The alias hostname must point to your CDN CNAME, shown in `ssl_provisioning.http_validation`. The request is served with the settings of the alias's CDN resource, so they must not block or redirect `/.well-known/acme-challenge/`. - `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. ## Response `200` Successful. - AliasDetail - `id` integer: Alias ID. - `cname` string: Alias hostname. Cannot be changed after creation. - `resource_id` integer: ID of the CDN resource whose settings the alias is served with. Cannot be changed after creation. - `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. - `challenge_type` 'dns_01' | 'http_01': Domain validation method used to issue the Let's Encrypt certificate for the alias. Possible values: - `dns_01` – Validation via a CNAME record for `_acme-challenge.`, shown in `ssl_provisioning.acme_delegation`. - `http_01` – Validation via an HTTP request to the alias hostname. The alias hostname must point to your CDN CNAME, shown in `ssl_provisioning.http_validation`. The request is served with the settings of the alias's CDN resource, so they must not block or redirect `/.well-known/acme-challenge/`. - `ssl_id` integer, nullable: ID of the SSL certificate served for the alias. - `active` boolean: Whether you have enabled the alias. Possible values: - `true` – The alias is enabled. - `false` – The alias is paused and is not served. - `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. - `status` 'inactive' | 'pending' | 'http_only' | 'active': 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. - `ssl_status` 'pending' | 'issued' | 'failed', nullable: 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. - `ssl_validity_not_after` string, nullable: Date and time when the served certificate expires (ISO 8601/RFC 3339 format, UTC). `null` while no certificate is served. - `created` string: Date and time when the alias was created (ISO 8601/RFC 3339 format, UTC). - `updated` string: Date and time when the alias was last changed (ISO 8601/RFC 3339 format, UTC). - `ssl_provisioning` object, nullable: 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. - `acme_delegation` AliasCnameRecord - `cname_name` string: Hostname to create the CNAME record for. - `cname_target` string: Value the CNAME record must point to. - `http_validation` AliasCnameRecord - `cname_name` string: Hostname to create the CNAME record for. - `cname_target` string: Value the CNAME record must point to. ## Other responses - `400`: Validation failed. - `403`: Aliases are not enabled for your account. - `404`: The alias does not exist. - `429`: Too many certificate issuance attempts have been started for the alias. ## Changes - **2026-10-21** `d034c0d6d6ff`: 1 breaking, 3 warning, 6 info - the `allOf[subschema #2]/ssl_provisioning/acme_delegation` response's property type changed from `object` to no type for status `200` - removed the optional property `allOf[subschema #2]/ssl_provisioning/acme_delegation/cname_name` from the response with the `200` status - removed the optional property `allOf[subschema #2]/ssl_provisioning/acme_delegation/cname_target` from the response with the `200` status - added the new `http_only` enum value to the `allOf[#/components/schemas/Alias]/status` response property for the response status `200` - …6 more - **2026-09-28** `9b685d687b49`: 1 breaking, 10 warning, 3 info - the response's body type changed from `object` to no type for status `200` - removed the optional property `active` from the response with the `200` status - removed the optional property `automated` from the response with the `200` status - removed the optional property `cname` from the response with the `200` status - …10 more - **2026-09-15** `adafd38a196b`: 1 info - endpoint added [Operation history](https://skmtc.dev/g-core/apis/gcore-openapi/changes/cdn/aliases/:alias_id/patch.md) --- [API](https://skmtc.dev/g-core/apis/gcore-openapi.md) - [All operations](https://skmtc.dev/g-core/apis/gcore-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/g-core/apis/gcore-openapi/revisions/a2b772345f3a?raw)