CloudWatch Postman
CloudWatch Postman is a Node server that sends data to Amazon CloudWatch. It enables you to serve an API with endpoints that add or update your metrics/your logs on CloudWatch with your AWS credentials.
- For the moment, configuration of this API is set with environment variables.
- Its first purpose is to serve some endpoints so an cliend-side application can call it to send data to CloudWatch.
- Prerequisites
- Quick start
- How to request the API
- API
- Configuration with Dotenv
- Contributing
- Resources
Prerequisites
- Node.js,
- Redis,
- Amazon CloudWatch,
- an AWS IAM account that can call CloudWatch with read and write access.
Quick start
Install the dependencies:
npm install
Choose an CLIENT_SECRET_KEY
and an ACCESS_TOKEN_SECRET_KEY
. These secret values
will be used by CloudWatch Postman to generate tokens to access the API.
Create a .env
file with these secrets and your
AWS credentials.
Start the app:
npm run serve
Test the API on http://localhost:8080/test.
How to request the API
You can request the API using a unique access token:
+--------------------+ +--------------------+
| | 2. Ask for an access token. | |
| | +------- POST /token -------> | |
| | | |
| Client | <---------------------------+ | |
| (your application) | 3. The API returns a valid | The API |
| | access token. | |
| | | cloudwatch-postman |
| 1. Create your | | |
| client token. | | |
| | | |
| | | |
| | | |
| | | |
| | 4. Make API calls with the | |
| | valid access token. | |
| | | |
| | +---- eg. POST /metric -----> | |
| | | |
| | (by default, the access token | |
| | is valid for one hour) | |
+--------------------+ +--------------------+
What is a unique access token?
As CloudWatch Postman is firstly meant to be called by a client-side application, unique access tokens can secure a little bit more the API endpoints.
You need to exchange your client token to obtain a unique access token. The latter have a default expiration of one hour.
When is a unique access token used?
Every endpoint, except the POST /token
one, needs an accessToken
to be
requested. We advise you to fetch it on your client-side application as soon as
possible if you know that you will need to query the API.
How to get a unique access token?
You can fetch an accessToken
on the POST /token
endpoint with your
client token.
How to generate your client token
This section explains how to generate an client token to request an access token for the API.
You will needs these values:
- the current timestamp,
- a random salt value,
- your
CLIENT_SECRET_KEY
,
Concatenate these 3 values and hash them with a sha256
algorithm digested in
base64
. Here is an
example in JavaScript:
import crypto from 'crypto'
const data = `${timestamp}${salt}${appSecretKey}`
const hash = crypto.createHash('sha256').update(data).digest('base64')
Then, generate your token:
- concatenate the date, the salt value and the hash with a
::
delimiter, - encode this string in
base64
.
Here is an example in JavaScript:
Buffer.from([timestamp, salt, hash].join('::')).toString('base64')
Tokens usage
Name | Usage | How to get it | Expiration |
---|---|---|---|
Access token | An access token is used for each call to the API endpoints, except POST /token and GET /test . It has to be included in the JSON body of your calls along with your other parameters { accessToken: "aValidAccessToken" } . |
You can fetch a valid access token on POST /token with your client token. |
By default, an access token has a one hour validity from the moment it is sent to the client. |
Client token | The client token is used to fetch a valid access token on POST /token . It has to be included in the JSON body of your call { clientToken: 'yourClientToken'} . |
You have to generate your client token on your side. | By default, a client token has a one day validity from the moment it is generated on your side. |
API
You can check the existing endpoints of this API in the documentation.
Configuration with Dotenv
You can set some variables with a .env
file and start the app with:
npm run serve
Example
# .env
AWS_ACCESS_KEY_ID=***
AWS_SECRET_ACCESS_KEY=***
AWS_REGION=***
CLIENT_SECRET_KEY=***
ACCESS_TOKEN_SECRET_KEY=***
Variables
The following variables can be setup in the .env
file:
Variable | Requirement | Description | Default value |
---|---|---|---|
AWS_ACCESS_KEY_ID |
Required | The AWS IAM user access key id. | |
AWS_SECRET_ACCESS_KEY |
Required | The AWS IAM user secret access key. | |
AWS_REGION |
Required | The CloudWatch region | |
CLIENT_SECRET_KEY |
Required | Your client secret key. You will share it on your consumer app to generate your client token. | |
ACCESS_TOKEN_SECRET_KEY |
Required | Your access token secret key. It is used to generate all the access tokens. | |
PORT |
Optional | The port on which the server is lauched | 8080 |
CORS_ALLOWED_ORIGIN |
Optional | A list of domain origins to which you grant the access to your API. Separate each origin with a comma: alice-in-wonderland.io, the-mad-hatter.com, tweedledee-tweedled.um |
* |
Contributing
Please refer to the contributing documentation.