Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


aws-blueprint example for a Twirp based API using AWS Serverless Application Module (SAM).


  • Multi-stage CI/CD via CodePipeline. Convention over configuration, designed for teams and feature branches.
  • CloudFront -> API Gateway -> Lambda (running Twirp). JSON as and application/protobuf binary support
  • Straight forward environment variable configuration. Supports pulling from SSM when running in AWS.
  • Simulate API Gateway -> Lambda locally via sam local start-api. Talks to DynamoDB local via docker-compose.
  • Local dev server with hot-reload (quicker developer iterations than sam local).
  • DynamoDB local with tools to create table(s) and load data.
  • Realtime CodePipeline source pulls via GitHub webhook.
  • Example showcases exchanging FireBase auth token for platform API JWT Token. Platform token passing utilizes 2-part cookies.
  • Twirp and sam local working with go modules
  • Go module vendoring
  • Automatic route53 alias entries with stage prefix. Ex: HTTPS support via ACM.


  1. AWS CLI and SAM CLI
  2. Create a github access token. This token will be used by the CI/CD to pull code. Required scopes: admin:repo_hook, repo
  3. S3 bucket to hold Lambda deployment zips. Only need 1 bucket per AWS account.
  4. Docker
  5. An SNS topic for CI/CD code promotion approvals. Subscribe your email address to it.
  6. Firebase account with Firebase Auth enabled
  7. Golang >= 1.12 (for go module support)

Quickstart - local dev server with auto-reload

  1. cp dotenv.example .env
  2. Download a FBase SDK private key JSON file. Paste as one line into .env::GOOGLE_APPLICATION_CREDENTIALS_JSON. On macOS: cat firebase-adminsdk.json | jq -c . | pbcopy. .env is only used when starting the server directly (not inside sam local). Feat req to address this.
  3. make setup/local will install go tooling and load local DynamoDB with sample data (dropping table if exists).
  4. make run/local-dev-api will go run server locally.
  5. Run curl -H 'Content-Type:application/json' -d '{"firebaseToken":"invalid"}' http:/localhost:8080/com.abpsamtwirp.platform.AuthSvc/Token

You should get an Invalid FBase token error. To get a valid FBase token, implement one of the SDKs into your app.

Simulate APIG + Lambda locally

This repo utlizes sam local start-api cli to simulate APIG->Lambda->Twirp.

Enviornment variables are pulled from sam-template.yml::Environment.Variables (not .env). To simulate how these will be set in cloudformation, the --parameter-overrides sam option is used. See run/sam-local-api in Makefile for an example.

  1. cp aws/sam-local/api-env.json aws/sam-local/sample-api-env.json
  2. Copy FBase SDK private key json to aws/sam-local/api-env.json, GOOGLE_APPLICATION_CREDENTIALS_JSON attribute as one line (cat firebase-adminsdk.json | jq -c '. | tojson' | pbcopy on macOS). This file is used to set env when running sam local.
  3. make run/sam-start-api
  4. Open and look at the console for the app env vars.

Startup is slow right? This simulates Lambda cold starts. See here.

Calling the API (Twirp)

Running make api-clients will generate clients for golang (rpc-clients/go), Typescript using Protobuf (rpc-clients/ts-protobuf), Typescript using JSON (rpc-clients/ts-json)

An example using Typescript clients can be seen at build-ts-clients/ts-test/main.ts.

An example using golang client can be seen at internal/authserver/server_test.go.

Deploying to AWS via CI/CD (AWS CodePipeline) using GitHub webhook

The CloudFormation parameters SSMFirebaseAdminSdkCreds and SSMJwtSecret in sam-template.yml dictates where in SSM to pull a value, which is then set as an env var in the lambda. In CodePipeline you set these parameter value on a stage-by-stage basis via aws/cloudformation/parameters. If you update the value in SSM, just execute a stack update to get the new env var into lambda.

  1. Clone this repo
  2. From SSM Console create a SSM parameter for every SSM* parameter defined in aws/cloudformation/parameters/*.json. For the SSM Param name use the VALUE of the SSM* attribute.
  3. Create a CI/CD pipeline via CloudFormation using aws/cloudformation/pipeline.yml using the name abp-sam-twirp--master--api--cicd (naming convention is [gitrepo]--[branch]--[eyecatcher]--cicd)
  4. git push and watch the pipeline. Will need to approve to promote to next stage. URL to your API is in the outputs of the ExecuteChangeSet CloudFormation.


  • Scan DynamoDB local: aws dynamodb scan --table-name local-SingleTable --endpoint-url http://localhost:8000


AWS Blueprint of a platform API using Twirp and SAM




No releases published


No packages published