Auth Providers

This guide explains how to manage Authentication Providers attached to a Frontdoor. Use these steps to list, create, update, and delete providers. Data you send must conform to the JSON Schema of the chosen provider type.

Why this matters

An Auth Provider defines how inbound requests are authenticated (for example, OIDC JWT validation, Google OAuth, etc).
Each provider has a type that determines its configuration schema. Retrieve schemas via the Auth Provider Types guide before creating providers.
Providers can often be enabled/disabled; updates should be designed to avoid authentication outages.
When an Auth Provider is updated, all Custom Frontend that has the provider configured will be updated.

Assumptions

The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
Expected headers for all API calls:

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

Tips

Keep provider names unique and descriptive (e.g., "oidc-okta-prod").
Start by creating in a staging Frontdoor, verify behavior, then promote to production.
Use PATCH for small, targeted changes; use PUT when replacing the full definition.

Operations

List auth providers

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers?page=0&size=20&sort=name,asc"

Response example

{
  "content": [
    { "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c", "name": "oidc-okta", "type": "OIDC", "enabled": true },
    { "id": "2ab4b3e2-1a2b-4c5d-8e9f-010203040506", "name": "api-keys", "type": "API_KEY", "enabled": true }
  ],
  "pageable": {"pageNumber": 0, "pageSize": 20},
  "totalElements": 2,
  "totalPages": 1
}

Get an auth provider 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/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true,
  "data": {
    "issuer": "https://your-org.okta.com",
    "clientId": "abc123",
    "audiences": ["api://default"]
  }
}

Create an auth provider

Note: Data must validate against the selected type schema.

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta",
        "type": "OIDC",
        "data": {
          "issuer": "https://your-org.okta.com",
          "clientId": "abc123",
          "audiences": ["api://default"]
        }
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers

Successful response example

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true
}

Partial update of an auth provider

Request example

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta-renamed"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta-renamed",
  "type": "OIDC",
  "enabled": true,
  "data": {
      "clientId": "703508275159-s061761h0b9r1v3istng21ih5qkd4li1",
      "clientSecret": "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",
      "scopes": [
          "openid",
          "email",
          "profile"
      ],
      "issuer": "https://okta.com/o/oauth2/v2/auth",
      "supportsPkce": true
  }
}

Put update an auth provider

Request example

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "oidc-okta",
        "type": "OIDC",
        "data": {
          "issuer": "https://your-org.okta.com",
          "clientId": "abc123",
          "audiences": ["api://default"]
        }
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

Response example

{
  "id": "0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c",
  "name": "oidc-okta",
  "type": "OIDC",
  "enabled": true,
  "data": {
      "clientId": "703508275159-s061761h0b9r1v3istng21ih5qkd4li1",
      "clientSecret": "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",
      "scopes": [
          "openid",
          "email",
          "profile"
      ],
      "issuer": "https://okta.com/o/oauth2/v2/auth",
      "supportsPkce": true
  }
}

Delete an auth provider

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/auth-providers/0f2fd3f7-0b85-4e4e-9d28-4d1a0c1e2b3c

The delete request has an empty response.

Technical Notes

Paths

- GET /frontdoor/\{frontdoorId\}/auth-providers[?page=0&size=20&sort=name,asc]
- GET /frontdoor/\{frontdoorId\}/auth-providers/{id}
- POST /frontdoor/\{frontdoorId\}/auth-providers
- PATCH /frontdoor/\{frontdoorId\}/auth-providers/{id}
- PUT /frontdoor/\{frontdoorId\}/auth-providers/{id}
- DELETE /frontdoor/\{frontdoorId\}/auth-providers/{id}

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.

Why this matters​

Assumptions​

Tips​

Operations​

List auth providers​

Get an auth provider by ID​

Create an auth provider​

Partial update of an auth provider​

Put update an auth provider​

Delete an auth provider​

Technical Notes​

Paths​

Common errors​

400 Bad Request (client error)​

401 Unauthorized (missing/expired token)​

403 Forbidden (not_authorized)​

Why this matters

Assumptions

Tips

Operations

List auth providers

Get an auth provider by ID

Create an auth provider

Partial update of an auth provider

Put update an auth provider

Delete an auth provider

Technical Notes

Paths

Common errors

400 Bad Request (client error)

401 Unauthorized (missing/expired token)

403 Forbidden (not_authorized)