# Client API: SSL

> Certificate inventory and issuance, plus HTTP-01 / DNS challenge workflows for domain validation.

Source: https://www.coritan.com/docs/api/reference/client/ssl/

Certificate inventory and issuance, plus HTTP-01 / DNS challenge workflows for domain validation.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/ssl/certificates`](#op-get-api-v1-ssl-certificates) | List SSL certificates for the authenticated user |
| POST | [`/api/v1/ssl/certificates`](#op-post-api-v1-ssl-certificates) | Request SSL certificate issuance for a domain owned by the user |
| DELETE | [`/api/v1/ssl/certificates/{domain}`](#op-delete-api-v1-ssl-certificates-domain) | Revoke/deactivate an SSL certificate for a domain |
| POST | [`/api/v1/ssl/certificates/{domain}/renew`](#op-post-api-v1-ssl-certificates-domain-renew) | Request certificate renewal for a domain |
| GET | [`/api/v1/ssl/certificates/{domain}/status`](#op-get-api-v1-ssl-certificates-domain-status) | Get SSL certificate status for a domain |
| POST | [`/api/v1/ssl/challenges/start`](#op-post-api-v1-ssl-challenges-start) | Start an SSL challenge for a domain |
| POST | [`/api/v1/ssl/challenges/{domain}/complete`](#op-post-api-v1-ssl-challenges-domain-complete) | Finalize verification and trigger certificate issuance |
| GET | [`/api/v1/ssl/challenges/{domain}/status`](#op-get-api-v1-ssl-challenges-domain-status) | Check the current verification status for a domain |

### List SSL certificates for the authenticated user {#op-get-api-v1-ssl-certificates}

`GET /api/v1/ssl/certificates`

List SSL certificates for the authenticated user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `25`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `certificates` | array of SSLCertificateResponse |
| `certificates[].id` | integer |
| `certificates[].domain` | string |
| `certificates[].route_id` | integer or null |
| `certificates[].zone_id` | integer or null |
| `certificates[].status` | string |
| `certificates[].issuer` | string or null |
| `certificates[].challenge_method` | string or null |
| `certificates[].issued_at` | string (date-time) or null |
| `certificates[].expires_at` | string (date-time) or null |
| `certificates[].last_renewal_at` | string (date-time) or null |
| `certificates[].renewal_attempts` | integer |
| `certificates[].error_message` | string or null |
| `certificates[].created_at` | string (date-time) or null |
| `certificates[].san_domains` | array of string |
| `certificates[].serial` | string or null |
| `certificates[].fingerprint_sha256` | string or null |
| `certificates[].requested_provider` | string or null |
| `certificates[].failover_from` | array of string |
| `total` | integer |

### Request SSL certificate issuance for a domain owned by the user {#op-post-api-v1-ssl-certificates}

`POST /api/v1/ssl/certificates`

Request SSL certificate issuance for a domain owned by the user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `route_id` | integer or null | no |
| `challenge_method` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Revoke/deactivate an SSL certificate for a domain {#op-delete-api-v1-ssl-certificates-domain}

`DELETE /api/v1/ssl/certificates/{domain}`

Revoke/deactivate an SSL certificate for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request certificate renewal for a domain {#op-post-api-v1-ssl-certificates-domain-renew}

`POST /api/v1/ssl/certificates/{domain}/renew`

Request certificate renewal for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get SSL certificate status for a domain {#op-get-api-v1-ssl-certificates-domain-status}

`GET /api/v1/ssl/certificates/{domain}/status`

Get SSL certificate status for a domain.

The certificate is the newest for the name itself, else for the parent's
wildcard (every claimed platform name carries one), else for the zone's
own wildcard, which carries the apex as a SAN (``certificate_lookup``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `domain` | string |
| `has_certificate` | boolean |
| `certificate` | SSLCertificateResponse or null |
| `certificate.id` | integer |
| `certificate.domain` | string |
| `certificate.route_id` | integer or null |
| `certificate.zone_id` | integer or null |
| `certificate.status` | string |
| `certificate.issuer` | string or null |
| `certificate.challenge_method` | string or null |
| `certificate.issued_at` | string (date-time) or null |
| `certificate.expires_at` | string (date-time) or null |
| `certificate.last_renewal_at` | string (date-time) or null |
| `certificate.renewal_attempts` | integer |
| `certificate.error_message` | string or null |
| `certificate.created_at` | string (date-time) or null |
| `certificate.san_domains` | array of string |
| `certificate.serial` | string or null |
| `certificate.fingerprint_sha256` | string or null |
| `certificate.requested_provider` | string or null |
| `certificate.failover_from` | array of string |
| `rate_limit` | SSLRateLimitResponse or null |
| `rate_limit.registered_domain` | string |
| `rate_limit.issued_last_7_days` | integer |
| `rate_limit.limit` | integer |
| `rate_limit.remaining` | integer |
| `rate_limit.allowed` | boolean |
| `wildcard` | boolean |

### Start an SSL challenge for a domain {#op-post-api-v1-ssl-challenges-start}

`POST /api/v1/ssl/challenges/start`

Start an SSL challenge for a domain. Returns method-specific instructions.

Methods:
- auto: automatically selects the best method
- dns_automatic: uses platform-managed DNS (requires DNS zone)
- dns_manual: returns TXT record for user to add to their external DNS
- http: verifies domain is pointed to this server, issues via HTTP-01

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `method` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Finalize verification and trigger certificate issuance {#op-post-api-v1-ssl-challenges-domain-complete}

`POST /api/v1/ssl/challenges/{domain}/complete`

Finalize verification and trigger certificate issuance.
For HTTP method: verifies domain points to server, then issues via HTTP-01.
For dns_manual: verifies TXT record exists, then issues via DNS-01.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Check the current verification status for a domain {#op-get-api-v1-ssl-challenges-domain-status}

`GET /api/v1/ssl/challenges/{domain}/status`

Check the current verification status for a domain.
Performs real-time DNS/IP resolution checks.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |