# awscred

> Resolves AWS credentials (and region) using env, file and IAM strategies

Latest version **1.5.0** (published 2019-10-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install awscred
pnpm add awscred
yarn add awscred
bun add awscred
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.0 |
| Published | 2019-10-14 |
| First published | 2015-04-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 45 |
| Author | Michael Hart |
| Maintainers | hichaelmart |
| Keywords | aws, credentials, region, resolver, resolve |

## Links

- npm: https://www.npmjs.com/package/awscred
- Repository: https://github.com/mhart/awscred
- Homepage: https://github.com/mhart/awscred#readme
- Issues: https://github.com/mhart/awscred/issues
- npm.io page: https://npm.io/package/awscred

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 1.5.0 (latest) — 2019-10-14
- 1.4.2 — 2018-11-18
- 1.4.1 — 2018-03-15
- 1.4.0 — 2018-03-14
- 1.3.0 — 2018-03-14
- 1.2.0 — 2016-07-08
- 1.1.0 — 2015-06-04
- 1.0.3 — 2015-04-24
- 1.0.2 — 2015-04-24

## README

awscred
-------

A small standalone library to resolve AWS credentials and region details
using, in order: environment variables, INI files, and HTTP calls (either to
EC2 metadata or ECS endpoints, depending on environment).  Queues HTTP calls to
ensure no thundering herd effect will occur when credentials expire.

Example
-------

```js
var awscred = require('awscred')

awscred.load(function(err, data) {
  if (err) throw err

  console.log(data.credentials)
  // { accessKeyId: 'ABC',
  //   secretAccessKey: 'DEF',
  //   sessionToken: 'GHI',
  //   expiration: Sat Apr 25 2015 01:16:01 GMT+0000 (UTC) }

  console.log(data.region)
  // us-east-1
})
```

Or just load the credentials, if you know the region already:

```js
awscred.loadCredentials(function(err, data) {
  if (err) throw err

  console.log(data)
  // { accessKeyId: 'ABC',
  //   secretAccessKey: 'DEF',
  //   sessionToken: 'GHI',
  //   expiration: Sat Apr 25 2015 01:16:01 GMT+0000 (UTC) }
})
```

Or just load the region, synchronously:

```js
console.log(awscred.loadRegionSync())
// us-east-1
```



API
---

### awscred.load([options], cb)
### awscred.loadCredentialsAndRegion([options], cb)

Resolves AWS credentials and region details, and calls back with an object containing
`credentials` and `region` properties as highlighted in the example above.

`options` include:

  - `filename`: the name of the INI file to parse, defaults to `'~/.aws/credentials'` for credentials and `'~/.aws/config'` for region
  - `profile`: the name of the INI profile to use, defaults to `'default'`
  - `timeout`: the ms timeout on the http call to the EC2 or ECS metadata service, defaults to `5000`
  - `credentialsCallChain`: array of functions to resolve credentials, defaults to `awscred.credentialsCallChain` below
  - `regionCallChain`: array of functions to resolve region, defaults to `awscred.regionCallChain` below

All options are also passed to `http.request`, so any standard Node.js HTTP
options may be used as well.

The following environment variables are checked by default:

  - `AWS_ACCESS_KEY_ID`, `AMAZON_ACCESS_KEY_ID`, `AWS_ACCESS_KEY`
  - `AWS_SECRET_ACCESS_KEY`, `AMAZON_SECRET_ACCESS_KEY`, `AWS_SECRET_KEY`
  - `AWS_SESSION_TOKEN`, `AMAZON_SESSION_TOKEN`
  - `AWS_REGION`, `AMAZON_REGION`, `AWS_DEFAULT_REGION`
  - `AWS_PROFILE`, `AMAZON_PROFILE`

### awscred.loadCredentials([options], cb)

As above, but only resolves credentials, does not look up region. Calls
back with just the credentials object (containing `accessKeyId`,
`secretAccessKey`, and optionally `sessionToken` and `expiration` properties).

### awscred.loadRegion([options], cb)

As above, but only resolves region, does not look up credentials. Calls
back with just the region string.

### awscred.loadRegionSync([options])

As above, but returns the region directly from this function using synchronous calls.

### awscred.credentialsCallChain

The array of credential loading functions used to determine call order. By default:
`[loadCredentialsFromEnv, loadCredentialsFromIniFile, loadCredentialsFromHttp]`

### awscred.regionCallChain

The array of region loading functions used to determine call order. By default:
`[loadRegionFromEnv, loadRegionFromIniFile]`

### awscred.loadCredentialsFromEnv
### awscred.loadRegionFromEnv
### awscred.loadRegionFromEnvSync
### awscred.loadCredentialsFromIniFile
### awscred.loadRegionFromIniFile
### awscred.loadRegionFromIniFileSync
### awscred.loadCredentialsFromHttp
### awscred.loadCredentialsFromEc2Metadata
### awscred.loadCredentialsFromEcs
### awscred.loadProfileFromIniFile
### awscred.loadProfileFromIniFileSync

Individual methods to load credentials and region from different sources.
`loadCredentialsFromHttp` will choose between `loadCredentialsFromEc2Metadata`
and `loadCredentialsFromEcs` depending on whether the
`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` environment variable is set (as it is on ECS).

### awscred.merge(obj, [options], cb)

Populates the `region` and `credentials` properties of `obj` using the
appropriate `load` method – depending on whether they're already set or not.

---
_Source: https://npm.io/package/awscred · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._