Self-serve account routes

Use /v1/me/* when you are acting as the signed-in operator of your personal Starkscan workspace rather than as an external API-key caller.

These routes back the hosted /api-key experience and expose the same personal-workspace self-serve control plane over HTTP.

Auth

Do not send X-Starkscan-Api-Key to this lane.

Authenticate with a Better Auth session instead:

• hosted browser flow: safe reads (GET / HEAD / OPTIONS) can use the Starkscan session cookies
• server or CLI flow: send Authorization: Bearer <better_auth_session_token>

If the session is missing or invalid, Starkscan returns 401 Unauthorized. If you try to POST or DELETE with cookies only, Starkscan returns 403 Forbidden with a WWW-Authenticate: Bearer header.

Routes

Rules

• GET /v1/me/api-keys returns metadata only. It never returns plaintext secrets.
• GET /v1/me/api-keys returns a bounded newest-first slice plus truncated=true when older historical keys exist outside the response.
• POST /v1/me/api-keys returns the plaintext key once for the new or rotated default key.
• If a default live key already exists, POST /v1/me/api-keys revokes it in the same operation and returns action=rotated.
• DELETE /v1/me/api-keys/{public_id} revokes the selected key and returns its final metadata snapshot.
• GET /v1/me/usage is a recent operational window, not a billing export, and it surfaces truncation flags on every bounded list.
• POST and DELETE on /v1/me/* are bearer-only on purpose. Starkscan rejects cookie-only mutations to avoid CSRF on key rotation/revocation.
• These routes are Cache-Control: no-store on purpose.

Examples

Export a session token if you are calling this lane outside the hosted browser:

export STARKSCAN_SESSION_TOKEN="<better_auth_session_token>"
# Optional: only set this for preview or self-hosted hosts.
# export STARKSCAN_BASE_URL="https://preview.example.com/api"

List keys:

curl \
  -H "Authorization: Bearer $STARKSCAN_SESSION_TOKEN" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/me/api-keys"

Issue or rotate the default key:

curl -X POST \
  -H "Authorization: Bearer $STARKSCAN_SESSION_TOKEN" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/me/api-keys"

Revoke one key:

curl -X DELETE \
  -H "Authorization: Bearer $STARKSCAN_SESSION_TOKEN" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/me/api-keys/<public_id>"

Inspect recent usage:

curl \
  -H "Authorization: Bearer $STARKSCAN_SESSION_TOKEN" \
  "${STARKSCAN_BASE_URL:-https://api.starkscan.co}/v1/me/usage"

Response shape highlights

• key list items include environment, scopes, status, masked key, rate-limit policy, and lifecycle timestamps
• issue/rotate responses include plaintextKey, apiKey, and revokedPublicIds
• usage snapshots include:
  • totalRequests
  • totalFailures
  • perKey
  • perKeyTruncated
  • recentRequests
  • recentRequestsTruncated
  • recentFailures
  • recentFailuresTruncated
• recent usage events include request id, status, app-observed latencyMs, API key public id, key label, key environment, and key scopes so support can trace client traffic by key/workspace without exposing secrets or raw auth-provider subject identifiers

See the API reference for the exact fields and schemas.