---
title: "bird workspace mtls certificate-authorities create"
description: "Add an mTLS certificate authority"
canonical: "https://bird.com/docs/cli/reference/workspace-mtls-certificate-authorities-create"
---

# `bird workspace mtls certificate-authorities create`

## Usage

```bash
bird workspace mtls certificate-authorities create [flags]
```

## Description

Add an mTLS certificate authority

Send one CA certificate as PEM. Prefer the issuing CA, because a root CA also trusts every certificate issued under it. To rotate, add the new CA before you remove the old one. Returns 409 when the CA limit of the workspace or of its organization is reached, or when the CA is already registered.

Build the request from flags, a JSON MTLSCertificateAuthorityCreate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

Browser confirmation: the review link goes to stderr, not stdout, as next[].url
in a JSON line that also carries confirmation\_id. The command then waits and
prints the result on stdout; --confirmation-id waits on an existing one.

## Procedure

Step 1 of 3 of "Require client certificates on API requests". Next: bird workspace mtls update.

## Examples

```bash
# print the body shape (no credentials needed)
bird workspace mtls certificate-authorities create --example

# the body it prints:
```

```json
{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----\n"
}
```

```bash
# add the issuing CA from a file
bird workspace mtls certificate-authorities create --certificate-file issuing-ca.pem
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                 | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `--certificate`      | One PEM-encoded X.509 certificate. (required; or in --body-file)  |
| `--certificate-file` | Read the PEM certificate from this file instead of --certificate. |
| `--response-schema`  | Print the fields this command returns, then exit                  |
| `--confirmation-id`  | Wait for an existing confirmation of this exact request           |

## Related

| Name                                                                                                                      | Description                          |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [`bird workspace mtls certificate-authorities delete`](/docs/cli/reference/workspace-mtls-certificate-authorities-delete) | Remove an mTLS certificate authority |
| [`bird workspace mtls certificate-authorities get`](/docs/cli/reference/workspace-mtls-certificate-authorities-get)       | Get an mTLS certificate authority    |
| [`bird workspace mtls certificate-authorities list`](/docs/cli/reference/workspace-mtls-certificate-authorities-list)     | List mTLS certificate authorities    |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)