test
Check connectivity from your machine to Base IdP, and confirm your client registration is live.
base-idp test is the first command you should run when a login flow is not
working. It checks three things in order: the health endpoint, the discovery
endpoint, and (if you pass a client id) the client-config endpoint. If all
three pass, the problem is not network and is not registration. The problem
is in your code.
npx base-idp test --client-id sq_live_yourappTesting Base IdP connection to https://authlayer.squareexp.com...
healthz: 200 OK
discovery: 200 OK
client-config: 200 OK
IdP is reachable.What each check does
healthz
Hits GET /healthz. This is the most basic possible check — it tells you
whether you can reach Base IdP over the network at all.
A failure here means:
- You are offline.
- You are on a network that blocks the issuer host.
- A corporate proxy is intercepting requests and not letting them through.
A success here means: network is fine, move on.
discovery
Hits GET /.well-known/square-identity. This is the discovery document — it
lists the issuer's endpoints (authorization_endpoint, token_endpoint,
paseto_public_key_endpoint).
A failure here is rare. It usually means the issuer URL you are pointed at
does not exist, which is a misconfigured --issuer flag or BASE_IDP_ISSUER
env override.
A success means the issuer is alive and reachable.
client-config
Hits POST /v1/client-config with your client id. This is the check that
actually involves your app.
A 200 here means the client id resolves to a real, active registration.
A 404 here means the client id does not exist. Either you mistyped it, or
the registration was deleted.
A 403 here means the registration exists but is disabled. Re-enable it in
Square Experience Cloud.
Options
| Flag | Description |
|---|---|
--issuer <url> | Override the issuer. Auto-resolves if omitted. |
--client-id <id> | Test the client-config endpoint for this client. |
--key <key> | Legacy anon key. Prefer --client-id. |
When to reach for it
This command is the answer to several different "what is going on" moments:
# Login UI never opens — is the network reachable?
npx base-idp test
# Login opens but client-config calls fail — is the client id right?
npx base-idp test --client-id sq_live_yourapp
# Pointing at a local Base IdP for dev — is it actually running?
npx base-idp test --issuer http://localhost:8080In every case the output isolates whose problem it is. Network. Issuer.
Registration. Your code. There are only four possibilities, and test
narrows it to one in about two seconds.