# `AWSAuth.Req`
[🔗](https://github.com/neilberkman/ex_aws_auth/blob/v1.4.1/lib/aws_auth/req.ex#L1)

Req plugin for AWS Signature V4 authentication.

This module provides seamless integration between `ex_aws_auth` and the
`Req` HTTP client library. It automatically signs requests with AWS Signature V4
without requiring manual header manipulation.

## Usage

    # Load credentials from environment
    creds = AWSAuth.Credentials.from_env()

    # Attach to a Req request
    Req.new(url: url, method: :post, body: body)
    |> AWSAuth.Req.attach(credentials: creds, service: "bedrock")
    |> Req.request()

    # Or create a reusable client
    client =
      Req.new(base_url: "https://bedrock-runtime.us-east-1.amazonaws.com")
      |> AWSAuth.Req.attach(credentials: creds, service: "bedrock")

    # Make multiple requests
    Req.post!(client, url: "/model/my-model/invoke", json: params)

## Options

  * `:credentials` - (required) `AWSAuth.Credentials` struct or keyword list with:
    * `:access_key_id` - AWS Access Key ID
    * `:secret_access_key` - AWS Secret Access Key
    * `:session_token` - AWS Session Token (optional)
    * `:region` - AWS region (optional, defaults to "us-east-1")

  * `:service` - (required) AWS service name (e.g., "s3", "bedrock", "lambda")

  * `:region` - AWS region (optional, overrides region from credentials)

## How it Works

The plugin adds a request step that:

1. Extracts the request method, URL, headers, and body
2. Normalizes Req's list-valued headers to string values for signing
3. Signs the request using AWS Signature V4
4. Returns headers in Req's expected format (`%{key => [value]}`)

## Examples

    # Basic usage with environment credentials
    creds = AWSAuth.Credentials.from_env()

    response =
      Req.new()
      |> AWSAuth.Req.attach(credentials: creds, service: "s3")
      |> Req.get!(url: "https://my-bucket.s3.amazonaws.com/object")

    # With explicit credentials
    creds = %AWSAuth.Credentials{
      access_key_id: "AKIAIOSFODNN7EXAMPLE",
      secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      region: "us-west-2"
    }

    response =
      Req.new(url: url, method: :post, json: data)
      |> AWSAuth.Req.attach(credentials: creds, service: "bedrock")
      |> Req.request!()

    # With session token (STS temporary credentials)
    creds = %AWSAuth.Credentials{
      access_key_id: "ASIAIOSFODNN7EXAMPLE",
      secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      session_token: "FwoGZXIvYXdzEBYaDHhBTEMPLESessionToken123",
      region: "us-east-1"
    }

    response =
      Req.new()
      |> AWSAuth.Req.attach(credentials: creds, service: "lambda")
      |> Req.post!(url: lambda_url, json: payload)

    # Override region
    response =
      Req.new()
      |> AWSAuth.Req.attach(
        credentials: creds,
        service: "s3",
        region: "eu-west-1"
      )
      |> Req.get!(url: "https://my-bucket.s3.eu-west-1.amazonaws.com/object")

# `attach`

```elixir
@spec attach(
  Req.Request.t(),
  keyword()
) :: Req.Request.t()
```

Attaches AWS Signature V4 signing to a Req request.

## Parameters

  * `request` - A `Req.Request` struct
  * `opts` - Keyword list of options (see module docs for details)

## Returns

A `Req.Request` with the AWS signing step prepended.

## Examples

    creds = AWSAuth.Credentials.from_env()

    request =
      Req.new(url: url)
      |> AWSAuth.Req.attach(credentials: creds, service: "bedrock")

---

*Consult [api-reference.md](api-reference.md) for complete listing*