---
name: o11y-auth
description: |
  Authenticate to the TiDB Cloud O11Y (Observability) platform via GitHub PAT.
  Returns a bearer token for data-export APIs, an auth0_token for the O11Y control plane, and AWS STS credentials for S3 access.
  Also provides the resolve_biz_type helper for mapping cluster deployType to O11Y bizType.
  Use when: authenticating to any O11Y service, resolving bizType from deployType,
  or any task that needs O11Y tokens or AWS credentials.
  Trigger phrases: "o11y auth", "o11y token", "data export token", "resolve biz type",
  "bizType mapping", "GitHub PAT for o11y".
---

# O11Y Authentication

Unified authentication for TiDB Cloud O11Y services via GitHub PAT.

A single call to o11y auth server `/client/auth` returns **three credential sets**:

| Credential | Variable | Use |
|-----------|----------|-----|
| Bearer token | `O11Y_TOKEN` | Data-export APIs (monitoringPipelines) |
| Auth0 token | `O11Y_AUTH0_TOKEN` | O11Y control plane (GS cluster lookup) |
| AWS STS credentials | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | S3 bucket access for exported data |

## Step 0: Obtain GitHub PAT (direct mode)

Proxy mode (`DS_PROXY_URL` set) skips this — the proxy holds the PAT, so a missing `GITHUB_PAT` is expected, not an error.

Direct mode: check `.env` for `GITHUB_PAT`. If missing, **stop and ask the user to provide their GitHub Personal Access Token following the [quickstart guide](https://pingcap.feishu.cn/wiki/Cgd4wb2RwijswskND0tcBj0In5g)**.

## Step 1: Authenticate

```bash
source {SKILL_PATH}/o11y-auth.sh
get_o11y_auth
# Exports: O11Y_TOKEN, O11Y_AUTH0_TOKEN,
#          AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
# Echoes:  O11Y_TOKEN to stdout
```

The script:

1. Reads `GITHUB_PAT` from `.env` -- prompts the user if missing and saves it
2. If cached token exists and is valid (not expiring within 5 min), restores all credentials
3. If expired/missing, fetches new credentials via o11y auth server and saves to `.env`
4. Retries transient `/client/auth` failures (`403`, `429`, `5xx`) before declaring auth failure

### Using the Tokens

```bash
source {SKILL_PATH}/o11y-auth.sh
get_o11y_auth

# Data-export API (monitoringPipelines)
curl -s "${GS_URL}/${BIZ_TYPE}/v1beta1/internal/clusters/${CLUSTER_ID}/monitoringPipelines" \
  -H "Authorization: Bearer ${O11Y_TOKEN}" ...

# O11Y control plane (GS cluster lookup)
curl -s "http://www.gs.us-west-2.aws.observability.tidbcloud.com/api/v1/clusters/" \
  -H "Authorization: Bearer ${O11Y_AUTH0_TOKEN}" -H "x-org-id: ${ORG_ID}" -H "x-biz-type: tidbcloud" -H "x-region-id: ${VENDOR}-${REGION}" ...

# S3 access (exported data)
aws s3 ls s3://o11y-task-<github_username>/
```

### .env Configuration

```bash
# Required (permanent)
GITHUB_PAT=ghp_your_github_pat

# Cached (managed by o11y-auth.sh)
O11Y_TOKEN=ey...
O11Y_AUTH0_TOKEN=ey...
O11Y_TOKEN_EXPIRES=1770427199
O11Y_AWS_ACCESS_KEY_ID=ASIA...
O11Y_AWS_SECRET_ACCESS_KEY=...
O11Y_AWS_SESSION_TOKEN=...
```

## BizType Reference

The `:bizType` URL path segment is constructed from **deployType** (cluster type) + **environment**.

### resolve_biz_type Helper

```bash
source {SKILL_PATH}/o11y-auth.sh

resolve_biz_type "premium" "prod"    # -> prod-tidbcloud-nextgen
resolve_biz_type "dedicated" "prod"  # -> tidbcloud (prod dedicated has no prefix)
resolve_biz_type "starter" "prod"    # -> prod-devtier
resolve_biz_type "premium"           # -> prod-tidbcloud-nextgen (default to prod)
```

### Full BizType Matrix (deployType x Environment)

| Base bizType | dev | staging | prod |
|-------------|-----|---------|------|
| `tidbcloud` | `dev-tidbcloud` | `staging-tidbcloud` | `tidbcloud` |
| `tidbcloud-nextgen` | `dev-tidbcloud-nextgen` | `staging-tidbcloud-nextgen` | `prod-tidbcloud-nextgen` |
| `devtier` | `dev-devtier` | `staging-devtier` | `prod-devtier` |

**Note**: Prod dedicated (`tidbcloud`) has no environment prefix. All others use `{env}-{baseBizType}`.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| 401 Unauthorized | Re-authenticate via `get_o11y_auth` |
| `/client/auth` returns `403` once, then works on retry | Treat as transient O11Y-side auth failure first; retry 2-3 times before blaming the PAT |
| Missing GITHUB_PAT | Set `GITHUB_PAT=ghp_...` in `.env` |
| S3 access denied | STS credentials expired -- re-authenticate |
| `null` token in response | GitHub PAT may be invalid or expired |

**Avoidance**:
- Reuse cached credentials within their TTL instead of calling `/client/auth` for every query.
- If a metrics query fails after a long-running session, refresh auth once and retry the query before changing diagnosis direction.

## Related Files

- `o11y-auth.sh` - Token + AWS credentials management, `resolve_biz_type` helper
- `.env` - GitHub PAT and cached credentials