# `ImagePipe.Source.S3.CredentialProvider`
[🔗](https://github.com/hlindset/image_pipe/blob/v0.2.0/image_pipe/lib/image_pipe/source/s3/credential_provider.ex#L1)

Behaviour for S3 credential providers.

A provider fetches AWS credentials for a bucket. Select it in the
`:credentials` setting of `ImagePipe.Source.S3`:

    credentials: {:provider, MyApp.VaultCredentials, path: "aws/creds/image-read"}

ImagePipe caches each result per provider, options, and bucket, and shares
it across requests. Temporary credentials are refreshed five minutes before
they expire. A cache entry is dropped after at least five minutes without a
request, and the next request fetches again. Credentials fetched by
`ImagePipe.Source.S3.CredentialWarmup` aren't dropped before their first
request. The built-in providers are listed under
[Credentials](`m:ImagePipe.Source.S3#module-credentials`).

# `credentials`

```elixir
@type credentials() :: keyword()
```

# `expiry`

```elixir
@type expiry() :: DateTime.t() | :never
```

# `scope`

```elixir
@type scope() :: String.t()
```

# `fetch_credentials`

```elixir
@callback fetch_credentials(scope(), keyword()) ::
  {:ok, credentials(), expiry()} | {:error, term()}
```

Fetches credentials for `scope`, the bucket name.

Returns a keyword list with `:access_key_id`, `:secret_access_key`, and an
optional `:token`, and an expiry: a `DateTime` for temporary credentials,
or `:never`. A result that has already expired, or any other expiry, is
rejected. When a refresh fails, the previous credentials are used until
they expire.

The result is shared by every request for the bucket, so it must depend
only on `scope` and the options.

# `validate_options`

```elixir
@callback validate_options(keyword()) :: :ok | {:error, term()}
```

Checks the provider's options when the source is configured, so bad options
fail at startup instead of on the first request. Return `:ok` when the
provider takes no options.

---

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