Skip to content
Raidboxes

SSL

Introduction

The Box SSL API provides endpoints for managing custom SSL certificates for specific boxes. This includes retrieving, creating, and deleting SSL certificates. All endpoints require JWT authentication.

Get custom SSL certificate

Get the custom SSL certificate for a specified box.

Endpoint

GET /v1/boxes/{id}/ssl

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the box
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 200 OK
  • Description: Response contains the custom SSL certificate for the specified box
  • Body:
{
  "domains": [
    "example.com",
    "www.example.com"
  ],
  "expires_at": "2024-12-31T23:59:59Z",
  "issuer": "Let's Encrypt Authority X3",
  "organization": "Example Inc.",
  "fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12",
  "lifespan_in_days": 90,
  "serial_number": "01:23:45:67:89:AB:CD:EF"
}
Field Type Description
domains array List of domains covered by the certificate
expires_at string Expiration date in ISO 8601 format
issuer string Certificate issuer name
organization string Organization name from the certificate
fingerprint string Certificate fingerprint in colon-separated hexadecimal
lifespan_in_days integer Certificate validity period in days
serial_number string Certificate serial number

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/boxes/{id}/ssl",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request
{
  "timestamp": "timestamp",
  "message": "Request could not be processed.",
  "path": "/v1/boxes/{id}/ssl",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f"
}

Create

Create a custom SSL certificate for a specified box.

Endpoint

POST /v1/boxes/{id}/ssl

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the box
Authorization Header string Yes Bearer token (JWT)

Request Body

Field Type Required Description
crt string Yes The SSL certificate content (PEM format)
key string Yes The private key for the certificate (PEM format)
bundle string No The certificate bundle/CA chain (PEM format)
csr string No The Certificate Signing Request (PEM format)

Example Request Body

{
  "crt": "-----BEGIN CERTIFICATE-----\\n...",
  "key": "-----BEGIN PRIVATE KEY-----\\n...",
  "bundle": "-----BEGIN CERTIFICATE-----\\n...",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\\n..."
}

Responses

Success Response

  • Status Code: 201 Created
  • Description: SSL certificate created successfully
  • Body:
{
  "domains": [
    "example.com",
    "www.example.com"
  ],
  "expires_at": "2024-12-31T23:59:59Z",
  "issuer": "Let's Encrypt Authority X3",
  "organization": "Example Inc.",
  "fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12",
  "lifespan_in_days": 90,
  "serial_number": "01:23:45:67:89:AB:CD:EF"
}

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/boxes/{id}/ssl",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request
{
  "timestamp": "timestamp",
  "message": "The crt field is required. (and 1 more error)",
  "path": "/v1/boxes/{id}/ssl",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f",
  "details": { ...
    "crt": [
      {
        "message": "The crt field is required."
      }
    ],
    "key": [
      {
        "message": "The key field is required."
      }
    ]
  } 
}

Delete

Delete the custom SSL certificate for a specified box.

Endpoint

DELETE /v1/boxes/{id}/ssl

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the box
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 204 No Content
  • Description: SSL certificate deleted successfully
  • Body: Empty

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/boxes/{id}/ssl",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request
{
  "timestamp": "timestamp",
  "message": "Request could not be processed.",
  "path": "/v1/boxes/{id}/ssl",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f"
}