Quickstart
Your first request in five minutes.
Pinal uses standard OAuth 2.1 with OpenID Connect, so any OAuth library works. Here's the whole flow, start to finish.
- 1Create an app
Name, icon, redirect URI and scopes. You get a client ID (and a secret, for web apps).
- 2Send people to sign in
Redirect to the authorize endpoint with PKCE. Pinal shows your consent screen.
- 3Get tokens
Exchange the code at the token endpoint for an access token.
- 4Call the API
Send the token as a Bearer header to any endpoint your scopes allow.
1. Create an app
Open the dashboard and choose New app. Pick the type that matches where your code runs:
- Web app: a server that can keep a secret. You get a client secret, shown once.
- Single-page app: runs entirely in the browser. No secret; PKCE protects the exchange.
- Native app: desktop or mobile. No secret; use PKCE and a loopback or custom-scheme redirect.
Add your redirect URI exactly as your code will send it, and choose only the scopes you need. The live preview shows the consent screen people will see.
2. Send people to sign in
Generate a PKCE verifier, keep it, and redirect to the authorize endpoint. Pinal handles sign-in, two-step verification and passkeys, then shows your consent screen.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(await sha256(verifier));
sessionStorage.setItem('pkce', verifier);
location.href = 'https://accounts.pinal.tech/api/auth/oauth2/authorize?' + new URLSearchParams({
response_type: 'code',
client_id: 'YOUR_CLIENT_ID',
redirect_uri: 'https://example.com/auth/callback',
scope: 'openid profile email notes.read',
state: crypto.randomUUID(),
code_challenge: challenge,
code_challenge_method: 'S256'
});They come back to your redirect URI with ?code=…&state=…. Check that state matches what you sent.
3. Exchange the code for tokens
curl -X POST https://accounts.pinal.tech/api/auth/oauth2/token \
-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d redirect_uri=https://example.com/auth/callback \
-d code_verifier="$VERIFIER"Access tokens last an hour. Ask for offline_access to also get a refresh token.
Verify ID tokens against the JWKS, or let your OIDC
library do it from the discovery document.
4. Call the API
curl https://api.pinal.tech/v1/notes?limit=5 \
-H "Authorization: Bearer $ACCESS_TOKEN"