Skip to content

Configuration Guide

Where Each Config Value Is Set

AWS Console

Config Location Notes
SES sender email SES → Verified Identities Must be verified before use
SES sending limits SES → Account Dashboard Request production access if in sandbox

Cloudflare Pages Dashboard

Config Project Notes
NEXT_PUBLIC_API_BASE_URL task-and-time-portal API Gateway URL
NEXT_PUBLIC_COGNITO_USER_POOL_ID task-and-time-portal From CDK output UserPoolId
NEXT_PUBLIC_COGNITO_CLIENT_ID task-and-time-portal From CDK output UserPoolClientId
NEXT_PUBLIC_COGNITO_REGION task-and-time-portal e.g., us-east-1
NEXT_PUBLIC_SENTRY_DSN task-and-time-portal Sentry project DSN
NEXT_PUBLIC_DOCS_URL task-and-time-portal URL of deployed MKDocs site

Shell Environment / CI Secrets

Set these before running cdk deploy or scripts/deploy.sh:

Variable Description
CDK_DEFAULT_ACCOUNT AWS account ID
CDK_DEFAULT_REGION AWS region (defaults to us-east-1)
XERO_CLIENT_ID Xero app credentials
XERO_CLIENT_SECRET Xero app credentials
XERO_REDIRECT_URI Xero OAuth callback URL
SLACK_SIGNING_SECRET Slack app signing secret
SLACK_BOT_TOKEN Slack bot OAuth token
ANTHROPIC_API_KEY Claude API key
SES_SENDER_EMAIL Verified SES sender
CONTACT_EMAIL Lead form recipient
SENTRY_DSN Sentry Lambda DSN
SENTRY_RELEASE Release version string
SENTRY_AUTH_TOKEN Sentry API token (deploy script)
SENTRY_ORG Sentry org slug (deploy script)

Local .env Files

File Purpose
apps/web/.env.local Web portal NEXT_PUBLIC_* variables for local dev
apps/desktop/.env Desktop app VITE_* variables
apps/homepage/.env.local Homepage variables (minimal)

How to Rotate Secrets

Xero OAuth Credentials

  1. Go to Xero Developer Portal
  2. Select your app → Configuration
  3. Generate new client secret
  4. Update XERO_CLIENT_SECRET in your shell/CI environment
  5. Run cdk deploy to update Lambda environment
  6. Existing tokens remain valid until they expire; new tokens will use the new secret

Slack App Credentials

  1. Go to Slack API Dashboard
  2. Select your app → Basic Information
  3. Signing Secret: Regenerate and update SLACK_SIGNING_SECRET
  4. Bot Token: OAuth & Permissions → Reinstall app if needed, update SLACK_BOT_TOKEN
  5. Run cdk deploy to update Lambda environment

Anthropic API Key

  1. Go to Anthropic Console
  2. Generate new API key
  3. Update ANTHROPIC_API_KEY in your shell/CI environment
  4. Run cdk deploy to update Lambda environment
  5. Old key can be revoked after deploy

Sentry Auth Token

  1. Go to Sentry → Settings → Auth Tokens
  2. Create new token with project:releases and org:read scopes
  3. Update SENTRY_AUTH_TOKEN in your shell/CI environment
  4. Used only by deploy script, not by Lambda runtime

Cognito User Pool Settings

Modifying via CDK

User pool settings are defined in infrastructure/lib/task-time-stack.ts:

  • Password policy (min length, required character types)
  • Sign-in aliases (email)
  • Auto-verify attributes
  • Custom attributes schema

Warning

Some Cognito settings cannot be changed after pool creation (e.g., custom attribute schema changes, sign-in alias changes). Check AWS docs before modifying.

Managing Users

  • Create internal user: AWS Console → Cognito → User Pool → Users → Create User
  • Set custom attributes: After creation, edit user and set custom:userRole (e.g., internal_admin) and optionally custom:customerId
  • Invite customer user: Use the web portal's customer management page → Users → Invite

CDK Outputs

After cdk deploy, the stack outputs:

Output Description Used By
ApiUrl API Gateway endpoint URL Frontend *_API_BASE_URL
UserPoolId Cognito User Pool ID Frontend *_COGNITO_USER_POOL_ID
UserPoolClientId Cognito App Client ID Frontend *_COGNITO_CLIENT_ID