Skip to main content

Authentication for NetFoundry REST APIs

This guide explains how to obtain an access token to call NetFoundry public REST APIs. It covers two options:

  • OAuth 2.0 (client credentials) — recommended for automation and service-to-service integrations.
  • API Account tokens — use a access token created in the console.

Once you have a token, include it in the Authorization header as a Bearer token for all API requests shown in the other guides.

Prerequisites​

  • Your organization's Identity Provider (IdP) domain and OAuth token endpoint (if using OAuth).
  • A client_id and client_secret registered with your IdP, with permissions to access NetFoundry APIs (if using OAuth).
  • Or an API Account with a generated access token from the NetFoundry console.
note

Always prefer short-lived tokens (OAuth) for automation. Access Tokens are convenient but should be stored securely and rotated regularly.

Obtain a token via OAuth 2.0 (client credentials)​

Overview​

  • Use your IdP's token endpoint to exchange client_id and client_secret for an access token.
  • Many IdPs require an audience or scope that matches the API resource. For NetFoundry Frontdoor APIs, audience commonly aligns with the API's base. Confirm with your administrator.

Request example:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "audience": "https://gateway.production.netfoundry.io/frontdoor",
        "scope": "frontdoor.read frontdoor.write"
      }' \
  https://YOUR_IDP_DOMAIN/oauth/token

Successful response example:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "frontdoor.read frontdoor.write"
}

Use the token in subsequent API calls:

TOKEN="eyJhbGciOi..."

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

Use an API Account access token​

Overview​

  • In the NetFoundry console, create an API Account (or open an existing one) and generate an access token.
  • The access token is a long-lived secret you can use directly with basic auth.
  • Store Access Tokens securely (e.g., vault, secret manager) and rotate them per your security policy.

Use an access token directly​

Request example:

ACCOUNT_ID="e2c7a6d0-e85a-4ca2-8e4b-3b2121cb3bec"
API_TOKEN="XXXXXXXXXXXXXXXX"

curl -s \
  -H "Authorization: Basic $ACCOUNT_ID:$API_TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/environments?page=0&size=20"

Optional: Exchange API key/secret for a short-lived token:

  • Some organizations configure an IdP client for API accounts. If you have an API key and secret, you may obtain a short-lived OAuth token using the same client credentials flow shown above.
  • Replace client_id and client_secret with your API account's key/secret and call your IdP's token endpoint.

Security best practices​

  • Do not hardcode secrets in source code. Use environment variables or a secrets manager.
  • Prefer the principle of least privilege: request only the scopes you need.
  • Rotate credentials regularly and revoke unused tokens promptly.

Where to go next​

With a working Bearer token, follow any guide under src/main/guides (e.g., shares.md, environments.md) and include the Authorization header as shown in each example.