I'm currently attempting to integrate my React client with my API gateway. I have the following architecture:

• React client using the aws-amplify/auth and aws-amplify/api libraries
• API Gateway with HTTP api (JWT authorizer)
• Lambda function attached to a /helloworld endpoint in the api gateway

The official Amplify documentation seems to be incomplete. In particular:

1. amplifyconfiguration.json and ResourcesConfig

amplifyconfiguration.json configuration structure and options seem to not be exhaustively listed anywhere. These are passed to Amplify.configure at the top-level of the app, listed in the documentation like this:

import config from "@/amplifyconfiguration.json";
Amplify.configure(config); // suggested in the documentation to be declared before the App function
export function App({ signOut, user }: WithAuthenticatorProps) { ... }

These configurations are expected to be of the type ResourcesConfig (not explained in the documentation). This becomes confusing specifically when attempting to use the aws-amplify/api library.

2. API library usage largely undocumented

Leveraging the API amplify request library apparently makes authentication something that does not need to be handled manually. A few issues with the documentation example:

• (await fetchAuthSession()).tokens?.idToken?.toString(); violates the top-level await incompatibility with the majority of browsers. This is suggested to be declared top-level in the documentation.
• apiName is required to abide by some(?) validation, however this is not explained at all in the Amplify documentation. Specifically, when making a request I see InvalidApiName: API name is invalid.. My apiName is set to the "Name" field for Api Gateway.

Questions

• What are the options and structure available/required for amplifyconfiguration.json? (EDIT: this does seem to be documented)
• What is the correct implementation of fetching the idToken?
  • if you intend to use the suggested documentation for automatically adding this to the correct headers in all requests - then how do you manage the REST: API: ... configuration in Amplify.configure()?
• Is the auth-token refresh flow listed anywhere for either the auth or api library?
  • how much is handled by the library? Will it automatically refresh a token?