Link fixes from issues in doc site repo

docs/getting-started/zowe-architecture.md

@@ -107,7 +107,7 @@ When running on z/OS, the server uses the jobname suffix of AD.
 ## Caching service
 
 The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The Caching service URL is `https://<ZOWE_HOST_IP>:7555`.
-For more information about the Caching service, see the [Caching service documentation](../extend/extend-apiml/api-mediation-caching-service.md).
+For more information about the Caching service, see the [Caching service documentation](../user-guide/api-mediation/api-mediation-caching-service).
 
 When the API gateway is running, this server is accessible at `https://<ZOWE_HOST_IP>:7554/cachingservice/api/v1`.
 When the API catalog is running, this server's API documentation is accessible at the API catalog tile `Zowe Applications` which can be viewed at `https://<ZOWE_HOST_IP>:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`

docs/getting-started/zowe-security-authentication.md

@@ -22,20 +22,20 @@ For more information, see the [Authentication for API ML services documentation]
 
 ## Authentication with Personal Access Token (PAT)
 
-A Personal Access Token (PAT) is a specific scoped JWT with a configurable validity duration. The PAT authentication method is an alternative to using a client certificate for authentication. It is disabled by default. To enable this functionality, see [the configuration documentation](../user-guide/api-mediation/api-gateway-configuration#personal-access-token).
+A Personal Access Token (PAT) is a specific scoped JWT with a configurable validity duration. The PAT authentication method is an alternative to using a client certificate for authentication. It is disabled by default. To enable this functionality, see [Enabling single sign on for clients via personal access token configuration](../user-guide/api-mediation/configuration-personal-access-token).
 
 **Benefits of PAT**
 
 - Long-lived. The maximum validity is 90 days.
 - Scoped. Users are required to provide a scope. It is only valid for the specified services.
 - Secure. If a security breech is suspected, the security administrator can invalidate all the tokens based on criteria as established by rules.
 
-For more information about PAT, see [the Personal Access Token documentation](../user-guide/api-mediation/api-mediation-personal-access-token).
+For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token).
 
 ## Authentication with SAF Identity Tokens
 The SAF Authentication Provider allows the API Gateway to authenticate the user directly with the z/OS SAF provider that is installed on the system.
 
-For more information about configuring the token, see the [Configure signed SAF Identity tokens (IDT) documentation](../user-guide/configure-zos-system#configure-signed-saf-identity-tokens-idt).
+For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system/#configure-signed-saf-identity-tokens-idt).
 
 ## Multi-factor authentication (MFA)
 

docs/user-guide/api-mediation-sso.md

@@ -24,13 +24,13 @@ There are two main types of components that participate in Zowe SSO through API
 * Zowe API ML client
 
    - This type of component is user-facing and can obtain user credentials through a user interface (web, CLI, desktop).
-   - API ML clients can be confidential or public.
+   - API ML clients can be private or public.
    - A Zowe API ML client calls API services through the API ML.
    - An example of such clients are Zowe CLI or Zowe Desktop. 
 
-* An API service accessed through Zowe API ML
+* API service accessed via Zowe API ML
 
-   - A service that is registered to API ML and is accessed through the API Gateway.
+   - A service that is registered to API ML and is accessed through the API ML Gateway.
    - Services are protected by an access token or PassTicket.
    - The access token or PassTicket can be validated by the called API service.
 
@@ -46,7 +46,7 @@ The following sections describe what is necessary to utilize SSO for both types
 
 This section describes the requirements that an API service needs to satisfy to adopt a Zowe SSO access token. 
 
-* The token received by the Gateway is first validated and then may be passed directly to the service. Alternatively, the Gateway can exchange the token for a PassTicket if the API service is configured to expect a PassTicket.
+* The token received by the API ML Gateway is first validated and then may be passed directly to the service. Alternatively, the API ML Gateway can exchange the token for a PassTicket if the API service is configured to expect a PassTicket.
 * The API service can validate the token and extract information about the user ID by calling the ZAAS `/query` endpoint. 
 * The alternative is to validate the signature of the JWT token using the public key of the token issuer (e.g. the API ML Gateway). The API service needs to have the API ML Gateway certificate along with the full CA certification chain in the API service truststore. 
 

docs/user-guide/api-mediation/using-api-mediation-layer.md

@@ -21,20 +21,53 @@ There are two primary use cases for using the API ML:
 
 See the following topics for detailed information about how to use the API Mediation Layer:  
 
-*  **Ways to use API ML via API ML Catalog**  
-    * [View Service Information and API Documentation](../api-mediation-view-service-information-and-api-doc.md)
-    * [Swagger "Try It Out" functionality](../api-mediation-swagger-try-it-out.md)
-    * [Swagger Code Snippets functionality](../api-mediation-swagger-code-snippets.md)
-    * [Static APIs refresh functionality](../api-mediation-static-api-refresh.md)
-    * [Change password via API Catalog functionality](../api-mediation-change-password-via-catalog.md) 
-    * [Onboarding a REST API service with the YAML Wizard](../onboard-wizard.md)
-
-* **Other features when using API ML**  
-    * [Using Metrics Service (Technical Preview)](../api-mediation-metrics-service.md)
-    * [API Mediation Layer Routing](../../extend/extend-apiml/api-mediation-routing.md)
-    * [Obtaining Information about API Services](../../extend/extend-apiml/service-information.md)
-    * [WebSocket support in API Gateway](../../extend/extend-apiml/websocket.md)
-    * [Personal Access Tokens](../../user-guide/api-mediation/api-mediation-personal-access-token.md)
-    * [SMF records](../../user-guide/api-mediation/api-mediation-smf.md)
+### Using Single Sign On (SSO)
 
+Three authentication methods can be used with single sign on:
+
+* [Authenticating with a JWT token](../authenticating-with-jwt-token)
+* [Authenticating with client certificates](../authenticating-with-client-certificates)
+* [Authenticating with a Personal Access Token](./authenticating-with-personal-access-token)
+
+### Using multi-factor authentication
+
+User identity verification can be performed by using multi-factor authentication. For more information, see [Using multi-factor authentication (MFA)](./using-multi-factor-authentication).
+
+### API Routing
+
+Various routing options can be used for APIs when using API Mediation Layer:
+
+* [Routing requests to REST APIs](./routing-requests-to-rest-apis)
+* [Routing with WebSickets](../routing-with-websockets)
+* [Using GraphQL APIs](use-graphql-api)
+* [Routing MultiTenancy Configuration](./api-mediation-multi-tenancy)
+
+### Learning more about APIs 
+
+API Mediation Layer makes it possible to view API information is a variety of ways:
+
+* [Obtaining information about API Services](../obtaining-information-about-api-services)
+* [Using Swagger "Try it out" in the API Catalog](../api-mediation-swagger-try-it-out)
+* [Using Swagger Code Snippets in the API Catalog](../api-mediation-swagger-code-snippets)
+
+### Administrating APIs
+
+* [Using Static API services refresh in the API Catalog](../api-mediation-static-api-refresh)
+* [Onboarding a REST API service with the YAML Wizard](../onboard-wizard)
+
+### Using the Caching Service
+
+As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. For details, see [Using the Caching service](./api-mediation-caching-service).
+
+### Using API Catalog
+
+There are various options for using the API Catalog:
+
+* [Viewing Service Information abd API Documentation in the API Catalog](../api-mediation-view-service-information-and-api-doc)
+* [Changing an expired password via API Catalog](../api-mediation-change-password-via-catalog)
+
+### Additional use case when usig API Mediation Layer
+
+* [Using Metrics Service (Technical Preview)](../api-mediation-metrics-service)
+* [SMF records](./api-mediation-smf)
 

docs/user-guide/authenticating-with-client-certificates.md

@@ -19,10 +19,10 @@ There is a limitation with respect to performing authentication using Z Secure S
 
 When sending a request to a service with a client certificate, the Gateway performs the following process to resolve authentication:
 
-* The client calls the service endpoint through the API ML Gateway with the client certificate.
-* The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway.
-* The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper.
-* The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service. 
+1. The client calls the service endpoint through the API ML Gateway with the client certificate.
+2. The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway.
+3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper.
+4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service. 
 
 :::note Notes:
 * Currently, ZSS is the default API that provides this mapping between the public part of the client certificate and SAF user ID. However, the recommended method is to use the internal API ML mapper. For information about the internal API ML mapper, see [Enabling the internal API ML mapper](#enabling-the-internal-api-ml-mapper) described in this article.
@@ -31,10 +31,10 @@ When sending a request to a service with a client certificate, the Gateway perfo
 
 When sending a request to the login endpoint with a client certificate, the Gateway performs the following process to exchange the client certificate for an authentication token:
 
-* The client calls the API ML Gateway login endpoint with the client certificate.
-* The client certificate is verified to ensure this is a valid TLS client certificate against the trusted CAs of the Gateway.
-* The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe release 2.14, the internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2.
-* The Gateway then performs the login of the mapped user and returns a valid JWT token.
+1. The client calls the API ML Gateway login endpoint with the client certificate.
+2. The client certificate is verified to ensure this is a valid TLS client certificate against the trusted CAs of the Gateway.
+3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe release 2.14, the internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2.
+4. The Gateway then performs the login of the mapped user and returns a valid JWT token.
 
 :::note
 ZSS is currently the default API that provides this mapping between the public part of the client certificate and SAF user ID. Using the internal API ML mapper is, however, the recommended method. 
@@ -86,7 +86,7 @@ This metadata can be used for TLS client authentication.
   Additional details are likely described in your security system documentation.
 
 2. Import the external CA to the truststore or keyring of the API Mediation Layer.
-3. Configure the Gateway for client certificate authentication. Follow the procedure described in [Enabling single sign on for clients via client certificate configuration](../user-guide/api-mediation/configuration-client-certificates.).
+3. Configure the Gateway for client certificate authentication. Follow the procedure described in [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates).
 
 :::caution Important:
 * PassTicket generation must be enabled for the Zowe runtime user. The user must be able to generate a PassTicket for the user and for the APPLID of z/OSMF. For more information, see [Configuring Zowe to use PassTickets](./api-mediation/configuration-extender-passtickets/#configuring-zowe-to-use-passtickets).

docs/user-guide/authenticating-with-jwt-token.md

@@ -13,7 +13,7 @@ This article describes how services in the Zowe API ecosystem are expected to ac
 For more information about authenticating with JWT tokens, see the Medium blog post [Single-Sign-On to z/OS REST APIs with Zowe](https://medium.com/zowe/single-sign-on-to-z-os-rest-apis-with-zowe-6e35fd022a95).
 :::
 
-By default, JWT tokens are produced by z/OSMF and the API Mediation Layer only serves as a proxy. For information about how to change who and how tokens are produced, see [Authentication Providers within Enable Single Sign On for Clients](../user-guide/api-mediation/configuration-jwt/#saf-as-an-authentication-provider)
+By default, JWT tokens are produced by z/OSMF and the API Mediation Layer only serves as a proxy. For information about how to change who and how tokens are produced, see [Authentication Providers within Enable Single Sign On for Clients](./api-mediation/configuration-jwt/#using-saf-as-an-authentication-provider).
 
 
 ## JWT Token-based Login Flow and Request/Response Format