AWSAWS Certified Generative AI Developer - Professional2026-102.3 Design and implement enterprise integration architectures
Expose legacy operations through authenticated boundaries
Completed by the knowledge check
Learning objective
Integrate legacy enterprise systems through authenticated API adapters and service boundaries
Core idea
An enterprise adapter gives an agent a narrow business interface while protecting the system that owns the transaction. The adapter translates protocols, checks authorization, and makes outcomes explicit. It should expose operations such as reading an authorized invoice or requesting an approved adjustment, rather than arbitrary database queries or an unrestricted backend URL.
Authentication has separate boundaries. The caller proves its identity to the API. The adapter proves its identity to the legacy service. The service decides whether that identity can perform the requested business operation. A valid token at the first boundary does not establish permission at the last one.
Treat generated arguments as untrusted application input. A model can propose an invoice identifier, but it cannot establish the caller’s tenant or grant itself access to that invoice. Keep those decisions in the adapter and the authoritative service. Tool exposure and AgentCore deployment are covered in 2.1.4; this lesson addresses the enterprise contract behind the tool.
How it works
Authenticate the caller at the API boundary
For an Amazon API Gateway HTTP API, use a JWT authorizer when callers present tokens from an identity provider. Configure the issuer and audience, and require appropriate route scopes through authorizationScopes. API Gateway checks claims including iss, aud or client_id, and expiration. A token must include at least one scope required by the route.
Scope checks are a coarse operation gate. They do not prove that a particular invoice belongs to the caller. The Lambda integration receives validated claims under requestContext.authorizer.jwt.claims; use a trusted subject-to-enterprise-identity mapping before checking object access. Do not substitute a tenant supplied in the request body for that mapping.
For callers using AWS credentials, HTTP API IAM authorization requires Signature Version 4 signing and execute-api permission for the route. Choose the authentication contract the caller can actually satisfy. A workload role and an end-user token represent different identities; decide which business operations each can initiate instead of treating either credential as interchangeable proof of user consent.
For credentials that are neither JWTs nor SigV4-signed requests, use an HTTP API Lambda authorizer with configured identitySource values; with authorizerPayloadFormatVersion: 2.0 and simple responses enabled, it returns isAuthorized after custom validation.
Translate a bounded business contract
Define accepted fields, allowed values, response types, and failure categories before translating to the legacy protocol. The adapter might turn a typed adjustment request into an enterprise API call. Keep model-specific prompt content outside this contract so that changing the model does not change the meaning of an adjustment.
Separate read and write operations. A read can return a business result, an authorization denial, or a dependency failure. A write also needs an outcome for an uncertain commit: the adapter timed out after sending the request and cannot determine whether the legacy service applied it. Retrying that case requires a business operation identifier or a status lookup, not another generated request with a different identifier.
Idempotency is an application contract here. Require the backend to recognize the same operation identifier, or maintain a durable operation record with reconciliation. Neither API Gateway authentication nor a Lambda handler automatically makes a legacy transaction idempotent. Reject unsupported behavior rather than claiming a guarantee the backend cannot enforce.
Keep backend access separate
If a Lambda adapter needs a legacy credential, retrieve it through AWS Secrets Manager rather than putting it in the prompt or tool arguments. The AWS Parameters and Secrets Lambda Extension can retrieve and cache secrets for the function. Plan how cached credentials behave during rotation, and give the function only the access it needs for its adapter role.
For an HTTP API that proxies to private HTTP services, API Gateway private integrations use a VPC link V2. The documented targets include Application Load Balancer and Network Load Balancer listeners, and services registered with AWS Cloud Map. For load balancers, specify an HTTP_PROXY integration with the listener ARN and VPC link. The HTTP API, VPC link, and target resources must belong to the same AWS account.
A VPC link is a connectivity mechanism. It does not perform business authorization or translate an arbitrary legacy protocol. If the system needs protocol translation, put an adapter service behind the reachable endpoint. The network path to an on-premises system is an additional design requirement; a VPC link alone does not establish it.
Private integration traffic uses HTTP by default. Set tlsConfig when the backend connection must use HTTPS. API Gateway also includes the stage portion in the backend request path by default; use parameter mapping to overwrite the path with $request.path when the backend expects a path without that prefix. These settings prevent a supposedly transparent adapter from changing transport security or routing unexpectedly.
Key distinctions and trade-offs
The important boundaries are:
| Boundary | Mechanism | Decision that remains in application code |
|---|---|---|
| Caller to HTTP API | JWT authorizer, IAM/SigV4, or Lambda authorizer | Which enterprise identity and tenant the caller represents |
| API to private HTTP backend | VPC link and private integration | Which business operation the endpoint exposes |
| Adapter to credentialed service | Secrets Manager retrieval | Which operations the credential may perform |
| Business operation to transaction | Backend contract and operation identifier | Whether retry is safe after an uncertain result |
A direct private proxy has fewer translation components, but it exposes the backend’s interface more directly. A Lambda or service adapter adds contract control and business validation, at the cost of another failure boundary. Choose it when the enterprise interface needs normalization, not merely because agents are involved.
Architecture / decision scenario
A finance assistant reads invoices and proposes adjustments to an enterprise resource planning system. Employees authenticate to the HTTP API with JWTs. Read and adjustment routes require different scopes. The adapter maps the validated subject to an employee identity, verifies invoice access, and requires the adjustment operation to satisfy the finance approval policy.
An existing private invoice-read service sits behind an Application Load Balancer. The team uses a VPC link, configures tlsConfig, and removes the stage prefix through $request.path mapping. The adjustment service requires translation and a service credential, so a Lambda adapter retrieves its secret and sends a bounded business request.
If the adjustment call times out after submission, the adapter reports an uncertain operation and reconciles by the original operation identifier. It does not translate the timeout into a definite rejection or issue a fresh adjustment. This preserves both authentication boundaries and the system of record’s ownership of the transaction.
Common exam traps
- Treating a JWT scope as authorization for every object behind the route.
- Using a request-body tenant identifier as trusted identity.
- Assuming private connectivity supplies authentication or protocol translation.
- Assuming a VPC link directly establishes an on-premises network path.
- Retrying a timed-out write without checking whether it committed.
- Putting backend credentials in model-visible context.
What to remember
Authenticate the caller, authorize the business operation, and authenticate the adapter to the backend as separate decisions. Use JWT scopes or IAM for the API gate, VPC links for supported private HTTP integration, and Secrets Manager for adapter credentials. Preserve uncertain transaction outcomes explicitly; an adapter is useful only if its contract remains truthful when the legacy system fails.
Knowledge check
An HTTP API route for invoice reads uses a JWT authorizer that requires the invoices:read scope. A signed-in employee requests one invoice by ID, and the request body also names a tenant. What must the adapter do before it returns the invoice?
A partner system must call your HTTP API. It authenticates with a static credential in a custom header, cannot obtain tokens from an identity provider, and has no AWS credentials. Which way of authenticating the partner fits?
execute-api permission for the routeAn HTTP API’s prod stage reaches an existing invoice service through a VPC link to an Application Load Balancer listener. The service’s logs show every request arriving, but with prod prepended to the path, and it returns 404 for all of them. Which change fixes this?
tlsConfig on the private integration$request.path/prod/... . Overwriting the path with $request.path removes it. tlsConfig changes the backend protocol to HTTPS, and the requests already reach the service, so connectivity and the integration target are not the fault.An adjustment adapter sends a write to the enterprise resource planning system, times out, and cannot tell whether the adjustment was applied. The caller asks again. What should the adapter do?