Domains, certificates and redirects

Domains for Applications, Compose stacks and buckets, TLS certificates, CDN checks and redirects.

A Domain sends a host name to a Service. Cloudgate requests a Let’s Encrypt certificate for it, or uses one you upload. Redirects rewrite requests on an Application’s Domains.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Domains in the user guide.

Domains

Create a Domain

POST/domains

Who can call it: Owner, Admin or Member. Needs domain: create, which a custom role can also grant.

Request body

Field	Type	Notes
`host`required	string	Not empty.
`path`	string	1 to 255 characters.
`internalPath`	string	1 to 255 characters.
`stripPath`	boolean
`port`	integer	1 to 65535.
`https`	boolean
`certificateType`	string	One of `letsencrypt`, `none`, `custom`, `stored`.
`customCertResolver`	string or null	Matches `^[A-Za-z0-9_-]{1,64}$`.
`customEntrypoint`	string or null	Matches `^[A-Za-z0-9_-]{1,64}$`.
`middlewares`	array of string
`forwardAuthEnabled`	boolean
`serviceName`	string
`domainType`	string	One of `application`, `compose`.
`applicationId`	string	The owning Application. Exactly one of applicationId, composeId or bucketId must be sent; a body carrying two is refused.
`composeId`	string	The owning Compose stack. Exactly one of applicationId, composeId or bucketId must be sent; a body carrying two is refused.
`bucketId`	string	The owning bucket on a Server, whose Garage S3 API the Domain routes to. Exactly one of applicationId, composeId or bucketId must be sent.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/domains \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "host": "shop.northwind.dev"
  }'

Generate a free sslip.io Domain

POST/domains/generate

Who can call it: Owner, Admin or Member. Needs domain: create, which a custom role can also grant.

Request body

Field	Type	Notes
`appName`required	string	Not empty.
`serverId`	string or null
`composeId`	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/domains/generate \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "appName": "storefront"
  }'

List an Application's Domains

GET/applications/{applicationId}/domains

Who can call it: Owner, Admin or Member. Needs domain: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`applicationId`required	path	string	The Application's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/domains \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List a Compose stack's Domains

GET/compose/{composeId}/domains

Who can call it: Owner, Admin or Member. Needs domain: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`composeId`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/compose/4Eo3MNRPQbdBs6dZEDtLs/domains \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List a bucket's Domains

GET/buckets/{bucketId}/domains

A Server bucket's Domains, under the same.

Who can call it: Owner, Admin or Member. Needs domain: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`bucketId`required	path	string	The bucket's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/buckets/GyPH5myXXSE8PYcyQeyJ2/domains \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get a Domain

GET/domains/{id}

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Domain's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/domains/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a Domain

PATCH/domains/{id}

Who can call it: Owner, Admin or Member. Needs domain: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Domain's id.

Request body

Field	Type	Notes
`host`	string	Not empty.
`path`	string	1 to 255 characters.
`internalPath`	string	1 to 255 characters.
`stripPath`	boolean
`port`	integer	1 to 65535.
`https`	boolean
`certificateType`	string	One of `letsencrypt`, `none`, `custom`, `stored`.
`customCertResolver`	string or null	Matches `^[A-Za-z0-9_-]{1,64}$`.
`customEntrypoint`	string or null	Matches `^[A-Za-z0-9_-]{1,64}$`.
`middlewares`	array of string
`forwardAuthEnabled`	boolean
`serviceName`	string
`domainType`	string	One of `application`, `compose`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/domains/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "host": "shop.northwind.dev",
    "path": "/",
    "internalPath": "/"
  }'

Delete a Domain

DELETE/domains/{id}

?force=true is the escape hatch for a Server that is gone for good, as on an Application Delete: without it, a Server that cannot be reached is a 409 naming it and the row is kept; with it, the row goes and the response names the router left in that Server's file. Compared to 'true' like the Application Delete's.

Who can call it: Owner, Admin or Member. Needs domain: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Domain's id.
`force`required	query	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE "https://cloudgate.octabyte.app/backend/domains/RAU6yAYUXFRdXdPLyLoPC?force=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Request a certificate again

POST/domains/{id}/ask-again

A failed cloud Domain's certificate, requested again.

Who can call it: Owner, Admin or Member. Needs domain: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Domain's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/domains/RAU6yAYUXFRdXdPLyLoPC/ask-again \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Certificates

List certificates

GET/certificates

Who can call it: Owner or Admin. Needs certificate: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/certificates \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a certificate

POST/certificates

Who can call it: Owner or Admin. Needs certificate: create, which a custom role can also grant.

Request body

Field	Type	Notes
`name`required	string	Not empty.
`certificateData`required	string	Not empty.
`privateKey`required	string	Not empty.
`serverId`	string or null

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/certificates \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "certificateData": "example",
    "privateKey": "<secret>"
  }'

Get a certificate

GET/certificates/{id}

Who can call it: Owner or Admin. Needs certificate: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The certificate's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/certificates/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a certificate

PATCH/certificates/{id}

Who can call it: Owner or Admin. Needs certificate: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The certificate's id.

Request body

Field	Type	Notes
`name`	string	Not empty.
`certificateData`	string	Not empty.
`privateKey`	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/certificates/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "certificateData": "example",
    "privateKey": "<secret>"
  }'

Delete a certificate

DELETE/certificates/{id}

Who can call it: Owner or Admin. Needs certificate: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The certificate's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/certificates/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Redirects

List redirects for an Application

GET/redirects

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`applicationId`required	query	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/redirects?applicationId=j9ct9tCzxUD9FjoxV2gtc" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a redirect

POST/redirects

Who can call it: Owner or Admin. Needs service: create, which a custom role can also grant.

Request body

Field	Type	Notes
`regex`required	string	1 to 1024 characters.
`replacement`required	string	1 to 1024 characters.
`permanent`	boolean
`applicationId`required	string	Not empty.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/redirects \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "regex": "example",
    "replacement": "example",
    "applicationId": "j9ct9tCzxUD9FjoxV2gtc"
  }'

Get a redirect

GET/redirects/{redirectId}

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`redirectId`required	path	string	The redirect's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/redirects/dvbW6tCLWxHxU9VphYVkH \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a redirect

PATCH/redirects/{redirectId}

Who can call it: Owner or Admin. Needs service: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`redirectId`required	path	string	The redirect's id.

Request body

Field	Type	Notes
`regex`	string	1 to 1024 characters.
`replacement`	string	1 to 1024 characters.
`permanent`	boolean

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/redirects/dvbW6tCLWxHxU9VphYVkH \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "regex": "example",
    "replacement": "example",
    "permanent": true
  }'

Delete a redirect

DELETE/redirects/{redirectId}

Who can call it: Owner or Admin. Needs service: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`redirectId`required	path	string	The redirect's id.
`force`required	query	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE "https://cloudgate.octabyte.app/backend/redirects/dvbW6tCLWxHxU9VphYVkH?force=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

CDN

Check a Domain behind a CDN

POST/domains/validate

Who can call it: Owner, Admin or Member. Needs domain: read, which a custom role can also grant.

Request body

Field	Type	Notes
`domain`required	string
`serverIp`	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/domains/validate \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "domain": "shop.northwind.dev"
  }'

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.