Getting Started: Access and Authentication

This tutorial takes you from zero to a working authenticated session on the Phenom internal tools. By the end you will have confirmed your Cognito credentials, accessed int-docs, and run a health check against the NEST API.

Prerequisites: a thephenom.app email account in the nest-access or int-docs-access Cognito group.

Step 1 — Confirm your Cognito group membership

All Phenom internal tools use the same Cognito pool: us-east-1_knEL7cqS3. Your account must be in the int-docs-access group to reach this site and the nest-access group to use the NEST application.

# Confirm group membership (requires AWS profile with Cognito read access)
aws cognito-idp admin-list-groups-for-user \
  --user-pool-id us-east-1_knEL7cqS3 \
  --username your@thephenom.app \
  --profile phenom \
  --region us-east-1 \
  --query 'Groups[].GroupName' \
  --output text

Expected output includes int-docs-access and nest-access.

If your account is missing from a group, contact the team admin to run:

aws cognito-idp admin-add-user-to-group \
  --user-pool-id us-east-1_knEL7cqS3 \
  --username your@thephenom.app \
  --group-name int-docs-access \
  --profile phenom \
  --region us-east-1

Step 2 — Sign in to int-docs

Open https://int-docs.matthewstevens.org (testing) or https://int-docs.thephenom.app (production). The terminal overlay loads and prompts for your authentication method.

Select [1] email + passphrase and enter your thephenom.app credentials.

On success the terminal clears and the Docsy site loads. You should see the nav bar: What’s New | Tutorials | How-to | Docs | Reference | Blog.

If you see USER_SRP_AUTH is not enabled for the client, you are hitting the wrong user pool client (usually the NEST app’s ALLOW_USER_SRP_AUTH-disabled client). Confirm the clientId in layouts/partials/nest-auth.html matches the int-docs app client in the Cognito console.

Step 3 — Run a quick NEST API health check

With your session live, confirm the public API endpoint is reachable:

curl -si https://api.thephenom.app/healthz | head -5
# Expected: HTTP/2 200 or HTTP/2 5xx (service may be degraded — check CloudWatch)

curl -sf -X POST https://api.thephenom.app/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}' | python3 -m json.tool
# Expected: {"data": {"__typename": "query_root"}}

If you get a 500, Hasura may be restarting or have a database connection issue. See the API runbook for remediation steps.

Step 4 — Access the NEST application

Navigate to https://nest.thephenom.app (production) or https://dev-nest.thephenom.app (staging/develop branch).

Sign in with the same Cognito credentials. Both environments share pool us-east-1_knEL7cqS3; they use separate app clients.

What’s next

• Agent MCP access tutorial — query int-docs from a Claude Code session without logging in via browser
• How-to: Runbooks — operational guides for every Phenom online asset
• API runbook — Hasura GraphQL and Auth service operations