Skip to Content
DocsQuickstart guidesRaw HTTP

cURL quickstart

🔑 Auth: client_id + client_secret (server-side) · 👤 This IS the login — standard OpenID Connect · 💻 Raw HTTP, no code · ⏱ ~5 minutes

What you’ll build: a complete login walked by hand — browser for the consent screen, cURL for everything else — so you can see exactly what your server will do.

Your real values are on your app’s API keys page in the Developer Portal .

Discovery lives at https://idp.valyd.work/api/.well-known/openid-configuration — everything below is listed there.

1. Create the app

In the Developer Portal  create an application, enable the profile scope, and register a redirect URI. For this walkthrough any URL you can read from the address bar works, e.g.:

http://localhost:8080/callback

Copy the client_id and the one-time client_secret.

2. Build the authorize URL and open it

Generate a random state, nonce, and PKCE code_verifier (plus its S256 code_challenge), then open this URL in a browser:

STATE=$(openssl rand -hex 16) # store it — you compare it on the callback NONCE=$(openssl rand -hex 16) CODE_VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n') # keep it for step 4 CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=') echo "https://idp.valyd.work/api/auth/oidc/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&response_type=code&scope=openid%20profile&state=$STATE&nonce=$NONCE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

Anatomy: response_type=code always; scope is space-separated (URL-encoded) and must include openid; code_challenge + code_challenge_method=S256 are required (PKCE, every client); state is recommended and echoed back unchanged (your CSRF check); nonce is recommended and bound into the id_token.

3. Grab the code from the callback

After you approve the consent screen, the browser lands on your redirect URI:

http://localhost:8080/callback?code=AUTH_CODE_HERE&state=...&iss=https%3A%2F%2Fidp.valyd.work

Check that state in the URL equals the $STATE you generated and iss is https://idp.valyd.work — then copy the code. It is single-use and expires in seconds, so exchange it immediately.

If you pressed Cancel (or something was wrong with the request) you get an error instead of a code:

http://localhost:8080/callback?error=access_denied&error_description=...&state=...&iss=https%3A%2F%2Fidp.valyd.work

4. Exchange the code for tokens

Form-encoded POST to the token endpoint (this is the step that must always run server-side — it carries your client_secret):

curl -X POST https://idp.valyd.work/api/auth/oidc/token \ -d grant_type=authorization_code \ -d code=AUTH_CODE_HERE \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET \ -d redirect_uri=http://localhost:8080/callback \ -d code_verifier=$CODE_VERIFIER

(Or authenticate with HTTP Basic — -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET — and drop the two client_* fields. Don’t send both.)

The response is top-level token JSON — no data wrapper:

{ "access_token": "eyJhbGciOi...", "refresh_token": "rfrsh_abc123...", "id_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "scope": "openid profile" }

The id_token is an RS256 JWT — in production verify it against the JWKS at https://idp.valyd.work/api/auth/oidc/jwks.json and check its nonce claim equals your $NONCE.

Errors are standard OAuth 2.0 JSON (no success/data wrapper):

{ "error": "invalid_grant", "error_description": "Invalid or expired authorization code" }

5. Read the user

curl -H "Authorization: Bearer ACCESS_TOKEN_HERE" \ https://idp.valyd.work/api/auth/oidc/userinfo

Returns the profile with valyd_id (the stable pseudonymous ID — use it as your user key) and id_verified. The same Bearer token also reads /api/auth/oidc/licenses and /api/auth/oidc/verifications, gated by the scopes the user approved.

✅

Checkpoint: the callback’s state matched yours; the token exchange returned HTTP 200 with top-level access_token, refresh_token, and id_token; and the userinfo call returned valyd_id and id_verified. Replaying step 4 with the same code fails with invalid_grant — codes are single-use.

Access tokens last ~1 hour. Renew with grant_type=refresh_token at the same endpoint — rotation is on, so always persist the new refresh_token you get back. Details in Authentication.

Troubleshooting

  • redirect_uri mismatch — the URI at /authorize and /token must be identical and exactly match a registered redirect URI. See Errors & troubleshooting.
  • invalid_grant — the code expired or was already exchanged, or code_verifier doesn’t match the code_challenge; go back to step 2 for a fresh one. See Errors & troubleshooting.
  • error=invalid_request on the callback — the authorize URL was missing code_challenge / code_challenge_method=S256. PKCE is required for every client.
  • invalid_scope / missing openid — scope must include openid, and every requested scope must be enabled on the app in the portal. See Errors & troubleshooting.

Next steps

  • Scopes — request verifications, email, or license scopes.
  • Account API — every endpoint the Bearer token can read.
  • Attach a verification — run a new KYC or license check with the user’s token so the proof saves to their Valyd account.
  • Ready to code it? The official SDK (npm install @valyd/sdk) does steps 2–5, plus PKCE and id_token verification, in two calls — see the Node.js quickstart.
Last updated on