Pinal Developers

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.

  1. 1Create an app

    Name, icon, redirect URI and scopes. You get a client ID (and a secret, for web apps).

  2. 2Send people to sign in

    Redirect to the authorize endpoint with PKCE. Pinal shows your consent screen.

  3. 3Get tokens

    Exchange the code at the token endpoint for an access token.

  4. 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"
Every endpoint, parameter and response is in the API reference, generated from openapi.json. Feed the spec to your favourite generator for a typed client in any language.