Taler ID — OAuth 2.0 / OIDC

Overview

Taler ID is an OpenID Connect (OIDC) provider that allows external applications to authenticate users and access their identity data (profile, email, KYC status, wallet address) using the standard Authorization Code + PKCE flow.

Quick Start (5 steps)

Client Registration

Any email-verified Taler ID user can register an OAuth client without contacting the Taler team. Self-registered clients are auto-approved with the default scope set (openid profile email offline_access). Sensitive scopes (kyc, wallet, phone) require a manual upgrade — email support@taler.tirol.

POST /oauth/register

curl -X POST https://id.taler.tirol/oauth/register \
  -H "Authorization: Bearer YOUR_TALER_ID_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.example/callback"],
    "logo_uri": "https://myapp.example/logo.png"
  }'

Successful response (RFC 7591):

{
  "client_id": "9d2a8e44-...-uuid",
  "client_secret": "base64url-secret",
  "client_id_issued_at": 1714293000,
  "client_secret_expires_at": 0,
  "client_name": "My App",
  "redirect_uris": ["https://myapp.example/callback"],
  "scope": "openid profile email offline_access",
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Manage your clients

• GET /oauth/clients — list your clients (no client_secret returned)
• GET /oauth/clients/:clientId — view one
• PATCH /oauth/clients/:clientId — update client_name, redirect_uris, logo_uri, scope
• DELETE /oauth/clients/:clientId — remove a client

Limits: 10 clients per user, 3 registrations per minute per IP.

Lost your client_secret? The secret is shown only at registration. To rotate, delete the client and register a new one (a dedicated rotation endpoint is planned).

Working Example: Node.js + Express

Below is the same demo as a full source listing — copy, run locally, and adapt to your own app. Uses the standard openid-client library which auto-discovers all endpoints from /oauth/.well-known/openid-configuration.

Step 1 — Register the client

Use any logged-in Taler ID user (with email_verified=true) to register your demo client. redirect_uris must include the local callback URL:

curl -X POST https://id.taler.tirol/oauth/register \
  -H "Authorization: Bearer YOUR_TALER_ID_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Demo App",
    "redirect_uris": ["http://localhost:3000/callback"]
  }'

Copy client_id and client_secret from the response — you'll need them in step 3.

Step 2 — Project files

Create a fresh directory taler-id-demo/ with three files:

package.json

{
  "name": "taler-id-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "start": "node server.js" },
  "dependencies": {
    "express": "^4.18.0",
    "openid-client": "^5.6.0",
    "dotenv": "^16.0.0"
  }
}

.env

TALER_ISSUER=https://id.taler.tirol/oauth
TALER_CLIENT_ID=<paste from step 1>
TALER_CLIENT_SECRET=<paste from step 1>
APP_BASE_URL=http://localhost:3000

server.js

import express from 'express';
import { Issuer, generators } from 'openid-client';
import 'dotenv/config';

const app = express();
const PORT = 3000;

// 1. Discover Taler ID OIDC endpoints automatically.
const issuer = await Issuer.discover(process.env.TALER_ISSUER);

// 2. Build a client with your registered credentials.
const client = new issuer.Client({
  client_id: process.env.TALER_CLIENT_ID,
  client_secret: process.env.TALER_CLIENT_SECRET,
  redirect_uris: [`${process.env.APP_BASE_URL}/callback`],
  response_types: ['code'],
});

// 3. In-memory PKCE store (use Redis or signed cookies in production).
const pendingLogins = new Map();

// 4. Landing page with the "Login with Taler ID" button.
app.get('/', (_req, res) => {
  res.send(`
    <h1>Demo App</h1>
    <a href="/login" style="
      display: inline-block; padding: 12px 24px;
      background: #167EF2; color: white;
      text-decoration: none; border-radius: 8px;
      font-family: system-ui;
    ">Login with Taler ID</a>
  `);
});

// 5. Start the OAuth flow: generate PKCE + redirect to /oauth/auth.
app.get('/login', (req, res) => {
  const code_verifier = generators.codeVerifier();
  const code_challenge = generators.codeChallenge(code_verifier);
  const state = generators.state();
  pendingLogins.set(state, code_verifier);

  const url = client.authorizationUrl({
    scope: 'openid profile email',
    code_challenge,
    code_challenge_method: 'S256',
    state,
  });
  res.redirect(url);
});

// 6. Receive the authorization code, exchange for tokens, fetch userinfo.
app.get('/callback', async (req, res) => {
  const params = client.callbackParams(req);
  const code_verifier = pendingLogins.get(params.state);
  pendingLogins.delete(params.state);

  if (!code_verifier) return res.status(400).send('Unknown state');

  const tokenSet = await client.callback(
    `${process.env.APP_BASE_URL}/callback`,
    params,
    { code_verifier, state: params.state },
  );

  const userinfo = await client.userinfo(tokenSet.access_token);

  res.send(`
    <h1>✅ Logged in</h1>
    <pre>${JSON.stringify(userinfo, null, 2)}</pre>
    <a href="/">← Back</a>
  `);
});

app.listen(PORT, () => {
  console.log(`Demo running on http://localhost:${PORT}`);
});

Step 3 — Run it

npm install
npm start
# Open http://localhost:3000 in a browser, click "Login with Taler ID"

You'll be redirected to Taler ID's login page, then to a consent screen showing your app's name and requested scopes, then back to /callback where the demo shows the user's profile (sub, email, name).

What this proves

• Self-service registration works end-to-end (step 1).
• Authorization Code + PKCE flow with our backend (steps 5–6).
• Token exchange returns access_token + id_token (and refresh_token if you add offline_access to scopes).
• /oauth/me userinfo endpoint returns claims for the logged-in user.

Adapt for production: replace the in-memory pendingLogins Map with Redis or signed cookies; persist tokens in a session store; add offline_access to scopes if you need refresh tokens; add CSRF protection to forms; serve over HTTPS.

Authorization Flow

Endpoints

Core OAuth 2.0 / OIDC

Authorization Request Parameters

Token Request Parameters

Token Lifetimes

Scopes & Claims

Example UserInfo Response

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Ivan Petrov",
  "given_name": "Ivan",
  "family_name": "Petrov",
  "email": "ivan@example.com",
  "email_verified": true,
  "phone_number": "+79001234567",
  "phone_number_verified": true,
  "kyc_status": "APPROVED",
  "kyc_type": "BASIC",
  "kyc_verified_at": "2026-01-15T10:30:00.000Z",
  "wallet_address": "5EZS5Lp5bdPdvcNfzaiFNjsTbtK78qWjCZVwACZFCEWVwRRp"
}

Code Examples

Node.js / TypeScript (with openid-client)

import { Issuer, generators } from 'openid-client';

// 1. Discover provider configuration
const issuer = await Issuer.discover('https://id.taler.tirol/oauth');

// 2. Create client
const client = new issuer.Client({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uris: ['https://yourapp.com/callback'],
  response_types: ['code'],
  token_endpoint_auth_method: 'client_secret_basic',
});

// 3. Generate PKCE
const code_verifier = generators.codeVerifier();
const code_challenge = generators.codeChallenge(code_verifier);
const state = generators.state();
const nonce = generators.nonce();

// 4. Build authorization URL
const authUrl = client.authorizationUrl({
  scope: 'openid profile email kyc wallet',
  code_challenge,
  code_challenge_method: 'S256',
  state,
  nonce,
});
// Redirect user to authUrl

// 5. Handle callback (on your /callback route)
const params = client.callbackParams(req);
const tokenSet = await client.callback(
  'https://yourapp.com/callback',
  params,
  { code_verifier, state, nonce }
);

console.log(tokenSet.access_token);
console.log(tokenSet.id_token);
console.log(tokenSet.claims());  // decoded id_token claims

// 6. Get user info
const userinfo = await client.userinfo(tokenSet.access_token);
console.log(userinfo);
// { sub, name, email, kyc_status, wallet_address, ... }

// 7. Refresh token
const refreshed = await client.refresh(tokenSet.refresh_token);
console.log(refreshed.access_token);

Python (with authlib)

from authlib.integrations.requests_client import OAuth2Session

client_id = 'your-client-id'
client_secret = 'your-client-secret'
redirect_uri = 'https://yourapp.com/callback'

# 1. Create session with PKCE
session = OAuth2Session(
    client_id, client_secret,
    redirect_uri=redirect_uri,
    code_challenge_method='S256',
)

# 2. Build authorization URL
auth_url, state = session.create_authorization_url(
    'https://id.taler.tirol/oauth/auth',
    scope='openid profile email kyc wallet',
)
# Redirect user to auth_url

# 3. Handle callback
token = session.fetch_token(
    'https://id.taler.tirol/oauth/token',
    authorization_response=callback_url,
)

# 4. Get user info
resp = session.get('https://id.taler.tirol/oauth/me')
userinfo = resp.json()
print(userinfo)
# {'sub': '...', 'email': '...', 'kyc_status': 'APPROVED', ...}

Flutter / Dart (with flutter_appauth)

import 'package:flutter_appauth/flutter_appauth.dart';

final appAuth = FlutterAppAuth();

// Authorize + get tokens in one step
final result = await appAuth.authorizeAndExchangeCode(
  AuthorizationTokenRequest(
    'your-client-id',
    'com.yourapp://callback',  // custom scheme redirect
    issuer: 'https://id.taler.tirol/oauth',
    scopes: ['openid', 'profile', 'email', 'kyc', 'wallet'],
  ),
);

print(result?.accessToken);
print(result?.idToken);
print(result?.refreshToken);

// Get user info
final response = await http.get(
  Uri.parse('https://id.taler.tirol/oauth/me'),
  headers: {'Authorization': 'Bearer ${result?.accessToken}'},
);

cURL (manual testing)

# 1. Generate PKCE code_verifier and code_challenge
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | head -c 43)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | \
  openssl dgst -sha256 -binary | \
  openssl base64 | tr '+/' '-_' | tr -d '=')

# 2. Open this URL in browser (user logs in + consents)
echo "https://id.taler.tirol/oauth/auth?\
client_id=walletx&\
response_type=code&\
scope=openid%20profile%20email%20kyc%20wallet&\
redirect_uri=http://localhost:3001/auth/callback&\
code_challenge=$CODE_CHALLENGE&\
code_challenge_method=S256&\
state=test123"

# 3. After login, copy the "code" from redirect URL and exchange:
curl -X POST https://id.taler.tirol/oauth/token \
  -u "walletx:your_client_secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&\
code=PASTE_CODE_HERE&\
redirect_uri=http://localhost:3001/auth/callback&\
code_verifier=$CODE_VERIFIER"

# 4. Use access_token to get user info
curl -H "Authorization: Bearer ACCESS_TOKEN_HERE" \
  https://id.taler.tirol/oauth/me

# 5. Refresh token
curl -X POST https://id.taler.tirol/oauth/token \
  -u "walletx:your_client_secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN_HERE"

# 6. Revoke token
curl -X POST https://id.taler.tirol/oauth/token/revocation \
  -u "walletx:your_client_secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Error Handling

Authorization Errors (redirect back to client)

Token Endpoint Errors (HTTP 400/401)

Interaction Errors (HTTP 401/403)

Security Requirements

Checklist