# List the fleet's certificates

`GET https://api.mailmasker.org/api/v1/admin/certstore`

Each TLS certificate the fleet hands out, soonest to expire first.

- Who can use it: Site admins
- Area: Fleet and status
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/admin-list-certificates

One entry per certificate name (`lineage`): the certificate the servers using that name should have now, the names it covers, when it expires and how many days are left. The issuing node publishes each renewal here and the servers pick it up from here; `sha256_fullchain` is what each of them compares with its own copy to tell whether it is out of date. No key material is ever included.

## Good to know

- Only the current certificate for each name is listed, not older ones.
- `published_by` is the issuing node's agent, and `promoted_at` is when this certificate became the current one.
- `days_remaining` counts whole days, and goes below 0 once a certificate is more than a day past its expiry.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/admin/certstore' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/admin/certstore',
    { Authorization => "Bearer $ENV{TOKEN}" })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

There is no homelab-cli command for this yet.

## Response

200 OK:

```json
[
  {
    "lineage": "mail.example.com",
    "serial": "04F3A2B19C7D5E6F8091A2B3C4D5E6F70812",
    "not_before": "2026-10-15 02:12:44-05",
    "not_after": "2027-01-13 01:12:43-06",
    "days_remaining": 70,
    "domains": ["mail.example.com", "imap.example.com", "smtp.example.com"],
    "sha256_fullchain": "6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f6b1f",
    "published_by": "agent+prod-homelab46@example.com",
    "published_at": "2026-10-15 03:12:51.208734-05",
    "promoted_at": "2026-10-15 03:12:51.208734-05"
  }
]
```