> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS CLI v2 native login

> Use aws login with a dedicated AI Reserve profile — OAuth PKCE browser authorization, real 15-minute STS credentials for your isolated AWS account, no static keys stored in config.

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.

> [!NOTE]
>
> **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):

```ini theme={"dark"}
[profile aireserve]
region = us-east-1
services = aireserve-login

[services aireserve-login]
signin =
  endpoint_url = https://api.aireserve.com
```

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.

> [!WARNING]
>
> 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:

```bash theme={"dark"}
aws login --profile aireserve
```

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`:

```bash theme={"dark"}
aws login --remote --profile aireserve
```

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):

```bash theme={"dark"}
export AWS_PROFILE=aireserve
```

## Session and credential details

| Property | Value |
| - | - |
| Credential type | Real AWS STS (`AccessKeyId` + `SecretAccessKey` + `SessionToken`) |
| Credential lifetime | 15 minutes (`expiresIn: 900`) |
| Token type | `aws_sigv4` — accepted by standard AWS SDK signing |
| Silent refresh | CLI re-calls `POST /v1/token` with `refreshToken` before expiry |
| Refresh window | 12 hours absolute from first login |
| After refresh window closes | `aws login` must be run again |
| Stored on disk | AWS Login cache in `~/.aws/login/cache/` (override with `AWS_LOGIN_CACHE_DIRECTORY`) |
| AWS service calls | Direct to AWS — credentials are real STS; AI Reserve is not in the path |

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:

```bash theme={"dark"}
aws sts get-caller-identity --profile aireserve
aws s3 ls s3://your-bucket --profile aireserve
aws ecr get-login-password --profile aireserve | docker login \
  --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com
```

These calls go **directly to AWS**. AI Reserve issues the credentials; it is not
involved in subsequent AWS API traffic.

## Logout

```bash theme={"dark"}
aws logout --profile aireserve
```

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:

```bash theme={"dark"}
# macOS (Homebrew)
brew upgrade awscli

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install --update

# Verify
aws --version   # must be 2.32.0 or later
```

### `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:

```bash theme={"dark"}
# Linux with timedatectl
sudo timedatectl set-ntp true

# macOS
sudo sntp -sS time.apple.com
```

### Debug output

Use the AWS CLI's global `--debug` option to inspect its HTTP calls:

```bash theme={"dark"}
aws --debug login --profile aireserve
```

Look for requests to `/v1/authorize` and `/v1/token` at `api.aireserve.com`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.