# Troubleshooting

Diagnose API configuration, environment and permission errors.

<a id="guide-content"></a>



<a id="diagnostics"></a>

### Check configuration before running tests

Use `INBOXSPEC_API_KEY` and `INBOXSPEC_API_URL`. The CLI accepts legacy key aliases `SEAGRASS_API_KEY` and `SEAGRASS_PI_KEY`, and URL aliases `INBOXSPEC_BASE_URL`, `SEAGRASS_API_URL` and `SEAGRASS_BASE_URL`, in that priority order after the preferred name. Explicit flags override environment values, which override the user config file. An empty preferred value fails instead of silently using an older key; conflicts report variable names only. Update shell scripts explicitly; the SDK takes constructor options.

```bash
inboxspec auth check --project-id "$EXPECTED_PROJECT_ID" \
  --environment staging --scope inboxes:write \
  --scope messages:read --scope messages:wait --json
```

Choose the environment you intend to test. `GET /v1/auth/check` reports project, scopes, key expiry and deployment context without returning the key. Console sign-in and project API authentication are separate.

-   `expired_key` or `revoked_key`: obtain an active credential through Credentials.
-   `invalid_key_or_environment`: check the selected key source and API origin. This deployment cannot know whether an unrecognized key belongs to another environment.
-   `project_mismatch`, `environment_mismatch` or `environment_unknown`: correct the expected context or server configuration.
-   `wrong_api_hostname` or `invalid_api_url`: use the API origin, with HTTPS outside loopback. Authenticated redirects are refused.
-   `insufficient_scope`: ask for the required permissions. DNS, TLS and timeout errors are transport failures, not evidence of an invalid key.