Skip to main content

Make your first five API calls

Sign in, list your accounts, create an HTTP load balancer and an upstream group, then read the group back. This creates saved resources; it does not configure a serving domain or route.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Before you begin​

You need a password-based sign-in, curl, jq, and an existing account API key with write access to HTTP load balancers and upstream groups. Set BALANCER_API_KEY to that key. This five-call path assumes sign-in does not require MFA; if MFA is enabled, complete the additional call in Authentication before listing contexts.

Set the base URL using the host shown in the Balancer portal:

export BALANCER_API_BASE='https://<your-api-host>'

The identity token in calls 1 and 2 lists your contexts. Calls 3 through 5 use the existing API key for your selected account. To use a bearer token for those calls instead, first enter an account context as described in Authentication; that requires an additional call.

Run the calls​

  1. Authenticate with your email and password.

    read -r -p 'Email: ' BALANCER_EMAIL
    read -r -s -p 'Password: ' BALANCER_PASSWORD
    printf '\n'
    jq -n --arg email "$BALANCER_EMAIL" --arg password "$BALANCER_PASSWORD" \
      '{email:$email,password:$password}' |
      curl --silent --show-error "$BALANCER_API_BASE/auth/login" \
        -H 'Content-Type: application/json' --data-binary @- > login.json
    unset BALANCER_PASSWORD
    BALANCER_IDENTITY_TOKEN=$(jq -r '.data.token' login.json)
    jq '{code,session:.data.session,expiresIn:.data.expiresIn,mfaRequired:.data.mfaRequired}' login.json

    Expect HTTP 200, an identity data.token, data.session.type equal to identity and data.expiresIn equal to 3600. Verify that you received a token rather than an MFA challenge before continuing.

  2. List the accounts and organizations available to your identity.

    curl --silent --show-error "$BALANCER_API_BASE/auth/contexts" \
      -H "Authorization: Bearer $BALANCER_IDENTITY_TOKEN" > contexts.json
    cat contexts.json

    Expect HTTP 200 with data.accounts and data.organizations arrays. Verify that the account associated with your existing API key appears. The remaining calls act in the key's account; listing contexts does not switch that key to another account.

  3. Create an HTTP load balancer.

    curl --silent --show-error "$BALANCER_API_BASE/http-loadbalancers" \
      -H "x-api-key: $BALANCER_API_KEY" -H 'Content-Type: application/json' \
      --data '{"name":"Example HTTP service"}' > load-balancer.json
    BALANCER_HTTP_LB_ID=$(jq -r '.data.httpLbId' load-balancer.json)
    cat load-balancer.json

    Expect HTTP 200 with data.httpLbId. Verify that it is present. HTTP/2 defaults to enabled and HTTP/3 to disabled. The name limit is 64 characters; the optional description limit is 255 characters.

  4. Add an account upstream group.

    curl --silent --show-error "$BALANCER_API_BASE/upstream-groups" \
      -H "x-api-key: $BALANCER_API_KEY" -H 'Content-Type: application/json' \
      --data '{"name":"Example origins"}' > upstream-group.json
    BALANCER_UPSTREAM_GROUP_ID=$(jq -r '.data.upstreamGroupId' upstream-group.json)
    cat upstream-group.json

    Expect HTTP 200 with data.upstreamGroupId. Verify that it is present. The group is an account resource; this call does not attach it to the load balancer or add an origin. Active health checks default to disabled, passive checks to enabled, connect timeout to 5000 milliseconds and healthy panic threshold to 50.

  5. Read the upstream group back.

    curl --silent --show-error \
      "$BALANCER_API_BASE/upstream-groups/$BALANCER_UPSTREAM_GROUP_ID" \
      -H "x-api-key: $BALANCER_API_KEY" > upstream-readback.json
    cat upstream-readback.json

    Expect HTTP 200 with data.upstreamGroupId, data.name and data.version. Verify that the identifier matches call 4 and the name is Example origins. This confirms the saved group, not edge activation.

Continue​

Use conditional updates for later PATCH and DELETE requests. Check changes and propagation when you configure origins, groups, domains and routes for traffic.