Move REST API setup instructions to installation page

welteki · alexellis · commit 469157b39397 · 2026-02-25T17:28:25.000Z
Move installation and configuration details for the REST API from
rest-api.md to installation.md so the API reference page serves
strictly as an endpoint reference.

- Add 'Setup the REST API' section to installation.md with access
  token, ingress, and OAuth configuration instructions
- Update rest-api.md to cross-reference the installation page
- Update configuration table to reflect clientApi.enabled defaults
  to true
- Update API docs to reflect auto generated access token

Signed-off-by: Han Verstraete (OpenFaaS Ltd) &lt;han@openfaas.com&gt;
diff --git a/docs/uplink/installation.md b/docs/uplink/installation.md
@@ -249,6 +249,77 @@ NAME                 READY   SECRET               AGE
 client-router-cert   True    client-router-cert   30m
 ```
 
+## Setup the REST API
+
+The REST API for Uplink is enabled by default and accessible on the same domain as the client-router under the `/v1` path prefix. For example, if your client-router domain is `uplink.example.com`, the API will be available at `https://uplink.example.com/v1`.
+
+See the [REST API reference](/uplink/rest-api/) to learn how to invoke the API and for a full list of endpoints.
+
+Optionally, the client-api can be exposed on a [separate domain](#configure-a-separate-api-domain).
+
+### Access token
+
+An access token is generated by Helm and stored as a Kubernetes secret during installation. This token can be used to authenticate with the API.
+
+If you need to create the token manually, for example to use a specific value, you can do so before installing the chart:
+
+```sh
+# Generate a new access token
+export token=$(openssl rand -base64 32|tr -d '\n')
+echo -n $token > $HOME/.inlets/client-api
+
+# Store the access token in a secret in the inlets namespace.
+kubectl create secret generic \
+  client-api-token \
+  -n inlets \
+  --from-file client-api-token=$HOME/.inlets/client-api
+```
+
+If the secret already exists, Helm will use the existing token instead of generating a new one.
+
+> See the [OAuth configuration](#configure-oauth) section for instructions on how to enable OAuth.
+
+### Configure OAuth
+
+You can configure any OpenID Connect (OIDC) compatible identity provider for use with Inlets Uplink.
+
+1. Register a new client (application) for Inlets Uplink with your identity provider.
+2. Enable the required authentication flows.
+  The Client Credentials flow is ideal for serve-to-server interactions where there is no direct user involvement. This is the flow we recommend and use in our examples any other authentication flow can be picked depending on your use case.
+3. Configure Client API
+
+    Update your `values.yaml` file and add the following parameters to the `clientApi` section:
+
+    ```yaml
+    clientApi:
+      # OIDC provider url.
+      issuerURL: "https://myprovider.example.com"
+
+      # The audience is generally the same as the value of the domain field, however
+      # some issuers like keycloak make the audience the client_id of the application/client.
+      audience: "uplink.example.com"
+    ```
+
+  The `issuerURL` needs to be set to the url of your provider, eg. `https://accounts.google.com` for google or `https://example.eu.auth0.com/` for Auth0.
+  
+  The `audience` is usually the client apis public URL although for some providers it can also be the client id.
+
+### Configure a separate API domain
+
+By default, the client-api is exposed on the same domain as the client-router under the `/v1` path prefix. If you prefer to use a separate domain, set the `clientApi.domain` field in your `values.yaml` file and enable the dedicated ingress:
+
+```yaml
+clientApi:
+  # Use a dedicated domain for the client API
+  domain: clientapi.example.com
+
+  tls:
+    ingress:
+      enabled: true
+```
+
+When a dedicated domain is set and `clientApi.tls.ingress.enabled` is `true`, a separate Ingress resource is created for the client-api.
+
 ## Download the tunnel CLI
 
 We provide a CLI to help you create and manage tunnels. It is available as a plugin for the inlets-pro CLI.
@@ -334,8 +405,10 @@ Overview of inlets-uplink parameters in `values.yaml`.
 | `clientRouter.service.nodePort` | Client router service port for NodePort service type, assigned automatically when left empty. (only if clientRouter.service.type is set to "NodePort")| `nil` |
 | `tunnelsNamespace` | Deployments, Services and Secrets will be created in this namespace. Leave blank for a cluster-wide scope, with tunnels in multiple namespaces. | `""` |
 | `inletsVersion` | Inlets Pro release version for tunnel server Pods. | `0.9.12` |
-| `clientApi.enabled` | Enable tunnel management REST API. | `false` |
-| `clientApi.domain` | Domain for a dedicated client API ingress. If left empty and ingress is enabled, the API is exposed on the client-router's domain under the `/v1` path prefix. | `""` |
+| `clientApi.enabled` | Enable tunnel management REST API. | `true` |
+| `clientApi.domain` | Domain for a dedicated client API ingress. By default the API is exposed on the client-router's domain under the `/v1` path prefix. | `""` |
+| `clientApi.tls.ingress.enabled` | Enable a dedicated ingress for the client API. Requires `clientApi.domain` to be set. | `false` |
+| `clientApi.tls.ingress.annotations` | Annotations to be added to the client API ingress resource. | `{}` |
 | `clientApi.image` | Container image used for the client API. | `ghcr.io/openfaasltd/uplink-api:0.1.5` |
 | `prometheus.create` | Create the Prometheus monitoring component. | `true` |
 | `prometheus.resources` | Resource limits and requests for prometheus containers. | `{}` |
diff --git a/docs/uplink/rest-api.md b/docs/uplink/rest-api.md
@@ -2,59 +2,7 @@
 
 Inlets uplink tunnels and namespaces can be managed through a REST API.
 
-A quick note on TLS: when you expose the uplink API over the Internet, you should enable HTTPS to prevent snooping and tampering.
-
-## Installation
-
-The REST API is part of the client-api component, and is disabled by default.
-You'll need to configure authentication, then update the values.yaml file and install the chart again.
-
-An access token needs to be created for the Client API before it can be deployed.
-
-```sh
-# Generate a new access token
-export token=$(openssl rand -base64 32|tr -d '\n')
-echo -n $token > $HOME/.inlets/client-api
-
-# Store the access token in a secret in the inlets namespace.
-kubectl create secret generic \
-  client-api-token \
-  -n inlets \
-  --from-file client-api-token=$HOME/.inlets/client-api
-```
-
-This token can be used to authenticate with the API.
-
-> See the [OAuth configuration](#configure-oauth) section for instructions on how to enable OAuth.
-
-Add the following parameters to your uplink `values.yaml` file and update the deployment:
-
-```yaml
-clientApi:
-  enable: true
-
-  tls:
-    ingress:
-      enabled: true
-```
-
-By default, the client-api will be exposed on the same domain as the client-router under the `/v1` path prefix. For example, if your client-router domain is `uplink.example.com`, the API will be available at `https://uplink.example.com/v1`.
-
-If you prefer to use a separate domain for the client-api, set the `clientApi.domain` field:
-
-```yaml
-clientApi:
-  enable: true
-
-  # Use a dedicated domain for the client API
-  domain: clientapi.example.com
-
-  tls:
-    ingress:
-      enabled: true
-```
-
-When a dedicated domain is set, a separate Ingress resource is created for the client-api.
+For setup instructions, including how to configure API authentication and enable the API ingress, see [Setup the REST API](/uplink/installation/#setup-the-rest-api).
 
 ## Authentication
 
@@ -74,7 +22,7 @@ Use the token as bearer token in the `Authorization` header when making requests
 
 ### OAuth
 
-If you have OAuth enabled you can obtain a token from your provider that can be used to invoke the Uplink Client API.
+If you have OAuth enabled you can obtain a token from your provider that can be used to invoke the Uplink Client API. See [Configure OAuth](/uplink/installation/#configure-oauth) for setup instructions.
 
 The example uses the client credentials grant. Replace the token url, client id and client secret with the values obtained from your identity provider.
 
@@ -266,28 +214,3 @@ curl -i \
   -H "Authorization: Bearer ${TOKEN}" \
   "$CLIENT_API/v1/namespace/$NAME"
 ```
-
-## Configure OAuth
-
-You can configure any OpenID Connect (OIDC) compatible identity provider for use with Inlets Uplink.
-
-1. Register a new client (application) for Inlets Uplink with your identity provider.
-2. Enable the required authentication flows.
-  The Client Credentials flow is ideal for serve-to-server interactions where there is no direct user involvement. This is the flow we recommend and use in our examples any other authentication flow can be picked depending on your use case.
-3. Configure Client API
-
-    Update your `values.yaml` file and add to following parameters to the `clientApi` section:
-
-    ```yaml
-    clientApi:
-      # OIDC provider url.
-      issuerURL: "https://myprovider.example.com"
-
-      # The audience is generally the same as the value of the domain field, however
-      # some issuers like keycloak make the audience the client_id of the application/client.
-      audience: "uplink.example.com"
-    ```
-
-  The `issuerURL` needs to be set to the url of your provider, eg. `https://accounts.google.com` for google or `https://example.eu.auth0.com/` for Auth0.
-  
-  The `audience` is usually the client apis public URL although for some providers it can also be the client id.
