Skip to main content

Custom Frontends

This guide explains how to manage Custom Frontends and retrieve DNS information.

Why this matters​

  • Custom Frontends let you bring your own hostname (e.g., apps.example.com) to the platform.
  • All Frontends need a publicly validated certificate to operate.
  • Custom Frontends are only available in the Frontdoor (account) that they are defined in.

Notes​

  • Status may remain PENDING until required records propagate.
  • After create DNS entries must be created to validate the certificate.

Assumptions​

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Operations​

Create a custom frontend​

Once the entity is created infrastructure is created to host the frontend. Along with this infrastructure a token is generated to validate the certificate. Creating a Custom Frontend with a configured Auth Provider will allow a Share to be optionally configured to use the Auth Provider to authenticate users. See Get DNS records to configure for the data to use with DNS setup.

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "hostname": "apps.example.com",
        "frontendId": "fnd-1a2b3c",
        "authProviderIds": [
          "43c46752-caae-4ab8-92ac-de50bed4fd9b"
        ]
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/custom-frontends

Response example

{
  "id": "cfe-123",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "status": "NEW",
  "domainName": "apps.example.com"
}

Get a custom frontend​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/custom-frontends/cfe-123

Response example

{
  "id": "cfe-123",
  "hostname": "apps.example.com",
  "frontendId": "fnd-1a2b3c",
  "status": "ACTIVE"
}

Get DNS records to configure​

Retrieves both A record and CNAME records to add to a DNS name server in order to facilitate creating a certificate.

Trying to access the DNS records before the infrastructure is ready will result in a 400 Bad Request. To know when a Custom Frontend is ready to show the DNS records it's recommended to use the Get a custom frontend endpoint and wait until the status is PENDING.

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/custom-frontends/cfe-123/dns-records

Response example

{
    "frontdoorId": "0edb9911-2b41-4fe3-8fd6-1e7260ac8d96",
    "customFrontendId": "dae9b6b5-18e3-45c6-b189-62d499e7004c",
    "domainName": "shares.example.com",
    "aRecord": {
        "name": "*.shares.example.com",
        "ipAddress": [
            "75.2.114.129",
            "166.117.134.68"
        ]
    },
    "cnameRecords": [
        {
            "name": "_a55a073461bf8c2f675655275518ed1d.shares.example.com.",
            "value": "shares.example.com.domains.zrok.sandbox.netfoundry.io"
        }
    ]
}

Update a custom frontend​

Only the Auth Providers of a Custom Frontend can be updated. To change the domain name of a Custom Frontend, it needs to be deleted and a new create a new one.

Request example

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "authProviderIds": [
          "43c46752-caae-4ab8-92ac-de50bed4fd9b",
          "89e9d95f-cab7-47bf-8997-a4f45300ceaa"
        ],
        "frontendId": "fnd-1a2b3c"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/custom-frontends

Response example

{
  "id": "cfe-123",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "status": "NEW",
  "domainName": "apps.example.com"
}

Delete a custom frontend​

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/custom-frontends/cfe-123

The delete request has an empty response.

Technical Notes​

Paths​

- POST /frontdoor/\{frontdoorId\}/custom-frontends[?page=0&size=20&sort=name]
- GET /frontdoor/\{frontdoorId\}/custom-frontends/{id}
- DELETE /frontdoor/\{frontdoorId\}/custom-frontends/{id}
- GET /frontdoor/\{frontdoorId\}/custom-frontends/{id}/dns-records

Common errors​

400 Bad Request (client error)​

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)​

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)​

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

  • Invalid token: The token is not valid.
  • The token does not grant access to the requested resource.
  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.