# space.highport.manage.setCertificateMode

> Published by [lexicons.highport.space](https://lexicon.garden/identity/did:plc:ciygg5hma4q7ah2kxaszkyob)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.setCertificateMode)
- [Documentation](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.setCertificateMode/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.setCertificateMode/examples)

## Definitions

### `space.highport.manage.setCertificateMode`

**Type**: `procedure`

Choose how names under a proven base get certificates. wildcard lets this service get one wildcard certificate for the base over DNS-01, through the base's own challenge target, and returns the record that delegates it. per-name ends that grant. The caller must own the base, which must be verified or active. Delegation does not need to be enabled.

#### Input

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mode` | `string` | Yes | per-name: one certificate per name, ending any wildcard grant. wildcard: grant this service a wildcard certificate for the base. A new grant after an earlier one ended gets a new challenge target. |
| `domain` | `string` | Yes | The base: a domain registered to the caller. |
| `acknowledgeCertificateGrant` | `boolean` | No | Must be true for wildcard. While the base's _acme-challenge record points at the challenge target, this service can get a publicly trusted certificate for the base and every name in its zone. Removing that record ends the grant. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mode` | `string` | Yes |  |
| `domain` | `string` | Yes |  |
| `records` | `array` | Yes | For wildcard, one record: the base's _acme-challenge CNAME pointing at its challenge target, with purpose certificate. Empty for per-name. |
| `verified` | `boolean` | Yes | Whether the record this mode needs is in place. For wildcard, false until the base's _acme-challenge record is found pointing at its challenge target. Always true for per-name, which needs no record. |

#### Errors

- **InvalidDomain**: Not a syntactically valid domain.
- **NotBaseOwner**: No verified or active registration of that domain belongs to the caller.
- **CertificateGrantNotAcknowledged**: mode is wildcard and acknowledgeCertificateGrant is not true.
- **WildcardNotOffered**: No wildcard certificate is offered for this domain: it is a name delegated under another base, it is under a base offered to anyone without DNS proof, or the deployment has no challenge zone. The error message says which.
- **CaaForbidsIssuance**: The base's CAA records block this mode. For wildcard, issuewild (or issue, if there is no issuewild) must allow this deployment's issuer, account and DNS-01. For either mode, issue records must not limit this issuer to DNS-01, because the probe and per-name certificates cannot use it. The error message names the blocking record.
- **RateLimitExceeded**: A new wildcard grant was requested during the deployment's cooldown after the base's last grant or ending, or while its previous wildcard is still being retired. Ending a grant is never limited.

## Raw Schema

```json
{
  "id": "space.highport.manage.setCertificateMode",
  "defs": {
    "main": {
      "type": "procedure",
      "input": {
        "schema": {
          "type": "object",
          "required": [
            "domain",
            "mode"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "description": "per-name: one certificate per name, ending any wildcard grant. wildcard: grant this service a wildcard certificate for the base. A new grant after an earlier one ended gets a new challenge target.",
              "knownValues": [
                "per-name",
                "wildcard"
              ]
            },
            "domain": {
              "type": "string",
              "maxLength": 253,
              "description": "The base: a domain registered to the caller."
            },
            "acknowledgeCertificateGrant": {
              "type": "boolean",
              "description": "Must be true for wildcard. While the base's _acme-challenge record points at the challenge target, this service can get a publicly trusted certificate for the base and every name in its zone. Removing that record ends the grant."
            }
          }
        },
        "encoding": "application/json"
      },
      "errors": [
        {
          "name": "InvalidDomain",
          "description": "Not a syntactically valid domain."
        },
        {
          "name": "NotBaseOwner",
          "description": "No verified or active registration of that domain belongs to the caller."
        },
        {
          "name": "CertificateGrantNotAcknowledged",
          "description": "mode is wildcard and acknowledgeCertificateGrant is not true."
        },
        {
          "name": "WildcardNotOffered",
          "description": "No wildcard certificate is offered for this domain: it is a name delegated under another base, it is under a base offered to anyone without DNS proof, or the deployment has no challenge zone. The error message says which."
        },
        {
          "name": "CaaForbidsIssuance",
          "description": "The base's CAA records block this mode. For wildcard, issuewild (or issue, if there is no issuewild) must allow this deployment's issuer, account and DNS-01. For either mode, issue records must not limit this issuer to DNS-01, because the probe and per-name certificates cannot use it. The error message names the blocking record."
        },
        {
          "name": "RateLimitExceeded",
          "description": "A new wildcard grant was requested during the deployment's cooldown after the base's last grant or ending, or while its previous wildcard is still being retired. Ending a grant is never limited."
        }
      ],
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "domain",
            "mode",
            "records",
            "verified"
          ],
          "properties": {
            "mode": {
              "type": "string",
              "knownValues": [
                "per-name",
                "wildcard"
              ]
            },
            "domain": {
              "type": "string"
            },
            "records": {
              "type": "array",
              "items": {
                "ref": "space.highport.defs#dnsInstruction",
                "type": "ref"
              },
              "description": "For wildcard, one record: the base's _acme-challenge CNAME pointing at its challenge target, with purpose certificate. Empty for per-name."
            },
            "verified": {
              "type": "boolean",
              "description": "Whether the record this mode needs is in place. For wildcard, false until the base's _acme-challenge record is found pointing at its challenge target. Always true for per-name, which needs no record."
            }
          }
        },
        "encoding": "application/json"
      },
      "description": "Choose how names under a proven base get certificates. wildcard lets this service get one wildcard certificate for the base over DNS-01, through the base's own challenge target, and returns the record that delegates it. per-name ends that grant. The caller must own the base, which must be verified or active. Delegation does not need to be enabled."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```