Skip to main content
The AWS CLI v2.32.0 aws login command supports custom signin endpoints. With a one-time profile configuration, aws login --profile aireserve opens a browser, you approve in one click, and the CLI receives real AWS STS credentials for your organization’s isolated AWS account. Subsequent AWS service calls go directly to AWS with those credentials — nothing routes through AI Reserve at the service layer.
Requirements. AWS CLI v2.32.0 or later, an active AI Reserve portal account, an org admin role in your organization, an active organization, and an active AWS account linked to it.

​
How it works

  1. aws login --profile aireserve builds an OAuth authorization request (PKCE, response_type=code) and opens GET /v1/authorize on the gateway.
  2. The gateway 302-redirects the browser to the AI Reserve portal approval page.
  3. You approve. The portal redirects the authorization code and state back to the CLI’s redirect URI:
    • Same-device: the redirect goes to a http://127.0.0.1:<port>/oauth/callback listener the CLI opened locally.
    • Cross-device (--remote): the redirect goes to GET /v1/sessions/confirmation, which 302-redirects to the portal confirmation page. That page shows a Base64 string (base64(state=<encoded>&code=<encoded>)) you copy and paste back into the CLI.
  4. The CLI calls POST /v1/token with the authorization code and its PKCE verifier (plus a DPoP proof header) to receive a 15-minute AWS STS credential bundle.
  5. For subsequent calls the CLI re-presents the refreshToken to POST /v1/token silently (no second browser prompt) until the 12-hour absolute refresh window closes.
  6. AWS service calls (s3, ec2, sts, ecr, …) use the STS credentials directly against AWS — they are not proxied through AI Reserve.

​
One-time profile setup

Add the following to your ~/.aws/config (create the file if it does not exist):
Keep both the profile’s services = aireserve-login setting and the matching [services aireserve-login] block in ~/.aws/config. Automatic credential refresh creates a new Sign-In client from this persistent profile configuration. Passing --endpoint-url to one aws login command is not a substitute: that override does not persist for later refreshes. What each line does:
  • services = aireserve-login — names a services section that holds endpoint overrides for this profile.
  • [services aireserve-login] — the endpoint override block. Only signin is set; s3, ec2, sts, bedrock-runtime, and every other AWS service URL is untouched.
  • signin / endpoint_url — tells aws login to call AI Reserve’s /v1/authorize and /v1/token instead of the default AWS Sign-In endpoint.
  • region — the default region for AWS service commands that use this profile. It does not affect routing to AI Reserve’s Sign-In endpoint.
Do not add endpoint overrides for ecs, s3, sts, or any other AWS service under [services aireserve-login]. Only signin should be set. Any additional override would redirect real AWS traffic to AI Reserve, which will return errors.

​
Sign in

​
Same-device (default)

Run in any terminal on the machine you will use the CLI from:
The CLI opens your default browser to the portal approval page. Sign in if prompted, approve the session request, and return to the terminal — the CLI completes automatically once the local 127.0.0.1 callback receives the authorization code.

​
Cross-device (no browser on the target machine)

When you cannot open a browser on the target machine — a remote server, CI runner, or container — pass --remote:
The CLI prints a URL. Open it in a browser on any device that is signed into the AI Reserve portal, approve the request, and the portal confirmation page displays a Base64 string. Paste that string back into the terminal prompt. The CLI decodes the string, extracts the authorization code, and calls POST /v1/token to complete login. The Base64 string is the standard encoding of state=<url-encoded-state>&code=<url-encoded-code>. It contains no AWS access key or portal password, but the one-time code is still sensitive: do not share it, and paste it only into the CLI session that produced the URL.

​
Default profile

To omit --profile aireserve on every command, export the environment variable in your shell profile (.bashrc, .zshrc, or equivalent):

​
Session and credential details

The STS credentials are issued for your organization’s isolated AWS account. They are accepted by standard AWS APIs exactly like any other temporary STS credential.

​
Using AWS services

After login, standard AWS commands work as usual with these credentials:
These calls go directly to AWS. AI Reserve issues the credentials; it is not involved in subsequent AWS API traffic.

​
Logout

This removes the cached credentials from ~/.aws/login/cache/ on the local machine. It does not make a network call to a revocation endpoint — the refresh token is removed from local storage only. Any in-flight requests using the existing STS session token complete normally (up to its 15-minute expiry). Logging out does not invalidate a copy of the refresh token held elsewhere. If the portal user, organization, or linked AWS account is suspended, AI Reserve refuses future refreshes immediately. Credentials AWS already issued can remain valid for up to 15 minutes.

​
Access requirements

Login succeeds only when all four conditions are met:
  • The AI Reserve portal account is active (not suspended).
  • The account holds an org admin role in the organization.
  • The organization is active.
  • An active AWS account is linked to that organization.
If a condition is not met, the portal approval page explains what needs attention. If access changes after approval, /v1/token returns AccessDeniedException.

​
Troubleshooting

​
aws login is not a recognized command

Your AWS CLI version is older than 2.32.0. Upgrade:

​
ValidationException or INVALID_REQUEST

The profile config contains an error. Verify:
  • services = aireserve-login appears inside [profile aireserve], not in a global or another profile block.
  • [services aireserve-login] uses the exact name from services =.
  • signin = endpoint_url = https://api.aireserve.com — check for extra spaces, a missing newline before endpoint_url, or a trailing slash after .com.

​
AccessDeniedException

One of the four access requirements is not met (active portal account, org admin role, active organization, active AWS account). Check in the portal that all four are satisfied. Contact your organization admin if you do not have an org admin role.

​
Cross-device: confirmation page does not appear

Restart aws login --remote to obtain a fresh URL. Open that exact URL in a browser signed into the portal, approve it, then copy the complete Base64 value from the confirmation page back to the waiting terminal.

​
ExpiredTokenException before 12 hours

The system clock on the machine may be skewed. AWS STS validation is clock-sensitive; a drift over five minutes causes early expiry. Sync the clock:

​
Debug output

Use the AWS CLI’s global --debug option to inspect its HTTP calls:
Look for requests to /v1/authorize and /v1/token at api.aireserve.com.