Skip to main content

Frontdoors

This guide explains how to create, retrieve, and delete Frontdoors, and how to view metrics.

Why this matters​

  • A Frontdoor is the top-level entry point your clients connect to.
  • You can look up a Frontdoor by ID or by organization convenience path.
  • Metrics endpoints summarize request volumes and errors across the Frontdoor.

Assumptions​

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

Operations​

Create a frontdoor​

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "prod-frontdoor",
        "organizationId": "35dc3fce-c69b-47b2-8a54-0b5d6d7afda1"
      }' \
  https://gateway.production.netfoundry.io/frontdoor

Response example

{
  "id": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "name": "prod-frontdoor",
  "organizationId": "35dc3fce-c69b-47b2-8a54-0b5d6d7afda1"
}

Get a frontdoor by ID​

Request example

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

Response example

{
  "id": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "name": "prod-frontdoor",
  "organizationId": "35dc3fce-c69b-47b2-8a54-0b5d6d7afda1"
}

Get a frontdoor by organization ID​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor?organizationId=35dc3fce-c69b-47b2-8a54-0b5d6d7afda1

Response example

{
  "id": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "name": "prod-frontdoor",
  "organizationId": "35dc3fce-c69b-47b2-8a54-0b5d6d7afda1"
}

Get sparklines​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/sparklines?duration=PT1H"

Delete a frontdoor​

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

The delete request has an empty response.

Technical Notes​

Metrics​

All accounts track data metrics, see Metrics for more information.

Paths​

- POST /
- GET /\{frontdoorId\}
- GET /[?organizationId={organizationId}]
- DELETE /\{frontdoorId\}
- GET /\{frontdoorId\}/metrics?duration=PT1H
- GET /\{frontdoorId\}/sparklines?duration=PT1H

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.