Open Civic Platform

OAuth2 para Mini Apps

Autentica ciudadanos con Bolivia ID usando un flujo Authorization Code estándar. Tus usuarios otorgan consentimiento explícito para compartir datos verificados de la identidad digital de Tarija.

Crear una app Ver el flujo

Authorization CodeHS256 JWTConsentimiento explícito

Inicio rápido

En 5 pasos tenés tu Mini App conectada a Bolivia ID

Registrá tu Mini App

Completá el formulario en el Dev Portal con nombre, Redirect URIs y scopes.

Esperá la aprobación

El equipo de Bolivia ID revisa tu aplicación. Recibirás una notificación cuando esté aprobada.

Redirigí ciudadanos

Enviá a tus usuarios a https://boliviaid.com/oauth/authorize?client_id=... y recibí el código en tu callback.

Intercambiá el código

Hacé POST al endpoint de token con tus credenciales client_id + client_secret y el código recibido.

Consultá el perfil

Llamá a UserInfo con el access token y recibí los datos del ciudadano según los scopes autorizados.

Flujo Authorization Code

OAuth2 estándar con PKCE implícito por HTTPS

Mini App

GET

Ciudadano

https://boliviaid.com/oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...Redirección del navegador

Ciudadano

Consent

Bolivia ID

Pantalla Permitir / CancelarEl ciudadano ve los scopes y decide

Ciudadano

302

Mini App

redirect_uri?code=AUTH_CODE&state=...El código viaja por URL (5 min TTL)

Mini App

POST

Bolivia ID

https://boliviaid.com/api/oauth/tokengrant_type=authorization_code + client_secret

Bolivia ID

200

Mini App

{ access_token, expires_in: 3600 }JWT firmado con HS256 — 1 hora de validez

Mini App

GET

Bolivia ID

https://boliviaid.com/api/oauth/userinfo (Authorization: Bearer ...)Datos según scopes: nombre, email, KYC

Scopes

Datos que una Mini App puede solicitar con consentimiento

profile

Nombre, Foto y Carnet

Tu nombre, foto de perfil y Bolivia ID

email

Correo electrónico

Tu dirección de correo electrónico verificada

kyc

Estado de verificación KYC

Si tu identidad fue verificada con KYC

Endpoints

API REST con JSON — Content-Type: application/json

GET

https://boliviaid.com/oauth/authorize

Pantalla de consentimiento del ciudadano. Recibe client_id, redirect_uri, scope y state como query params.

Auth: Sesión de ciudadano

POST

https://boliviaid.com/api/oauth/token

Server-to-server. Intercambia un authorization code por un JWT access token válido por 1 hora.

Auth: client_id + client_secret

GET

https://boliviaid.com/api/oauth/userinfo

Devuelve datos del ciudadano según los scopes autorizados. Protegido con Bearer token.

Auth: Authorization: Bearer {token}

POST

https://boliviaid.com/api/oauth/notify

Envía una notificación push al ciudadano (máx. 3/hora). Requiere consentimiento previo via OAuth.

Auth: Authorization: Bearer {token}

Ejemplos de código

JavaScript (fetch) y curl listos para copiar y pegar

JavaScriptjs

// 1. Redirigir al ciudadano
  const params = new URLSearchParams({
    client_id: "tic_...",
    redirect_uri: "https://miapp.com/callback",
    scope: "profile email",
    state: crypto.randomUUID(),
  });
  window.location.href = `https://boliviaid.com/oauth/authorize?${params}`;
  
  // 2. En tu callback — intercambiar código
  const tokenRes = await fetch("https://boliviaid.com/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });
  const { access_token } = await tokenRes.json();
  
  // 3. UserInfo
  const profile = await fetch("https://boliviaid.com/api/oauth/userinfo", {
    headers: { Authorization: `Bearer ${access_token}` },
  }).then((r) => r.json());

curlbash

# Intercambiar código por token
  curl -X POST https://boliviaid.com/api/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code" \
    -d "code=AUTH_CODE" \
    -d "client_id=tic_..." \
    -d "client_secret=SECRET" \
    -d "redirect_uri=https://miapp.com/callback"
  
  # Consultar perfil
  curl https://boliviaid.com/api/oauth/userinfo \
    -H "Authorization: Bearer ACCESS_TOKEN"

Redirect URIs

Reglas de Redirect URIs:
  • Coincidencia exacta (sin wildcards, sin path traversal)
  • Deben usar HTTPS en producción
  • Para desarrollo local: http://localhost:3000/callback
  • Se configuran en el Dev Portal y se validan en cada request

Notificación pushbash

# Enviar notificación al ciudadano (máx. 3/hora, intervalo 10 min)
curl -X POST https://boliviaid.com/api/oauth/notify \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Tu pedido fue aceptado","cuerpo":"El profesional confirmó tu consulta.","href":"/mis-pedidos","idempotenciaKey":"order-123-msg"}'

Seguridad

Implementamos las mejores prácticas de OAuth2

JWT HS256

Access tokens firmados con OAUTH_JWT_SECRET (≥ 32 bytes). Expiran en 1 hora.

Códigos single-use

Authorization codes expiran en 5 minutos y solo se pueden usar una vez. Almacenados en DB.

Secrets hasheados

Client secrets se almacenan con SHA-256. El texto plano solo se muestra al crear o regenerar.

Redirect URI exacta

Validación por coincidencia exacta. Sin wildcards, sin path traversal, sin substring matching.

Revocación instantánea

Tokens se revocan vía flag en la base de datos. No se necesita JWT blacklist.

Scope enforcement

Cada endpoint de UserInfo solo devuelve los campos correspondientes a los scopes autorizados.

Botón de inicio de sesión

Usa el botón oficial en tu app — es obligatorio para la verificación

Vista previa

Continuar con Bolivia IDContinuar con Bolivia IDContinuar con Bolivia ID

Guías de uso

Mínimo 36 px de altoNo cambiar colores ni logoNo recortar el logoFondo contrastante

Uso obligatorio para apps verificadas.Las apps que soliciten el badge "Verificada por Bolivia ID" deben usar este botón en su pantalla de login — no reemplazar con texto genérico.

React / Next.jstsx

// Copia el archivo chapaco-id-button.tsx desde
// github.com/tarija-id/tarija-id → components/auth/
import { ChapacoIdButton } from "@/components/auth/chapaco-id-button";

<ChapacoIdButton
  clientId="tu_client_id"
  redirectUri="https://tuapp.com/callback"
  scope="profile email"
/>

HTML purohtml

<!-- HTML puro / cualquier framework -->
<a href="https://tarija.id/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=profile&response_type=code"
   style="display:inline-flex;align-items:center;gap:10px;padding:10px 18px;
          background:#0f172a;color:#fff;border-radius:14px;text-decoration:none;
          font-family:system-ui;font-size:14px;font-weight:600;">
  <svg viewBox="0 0 32 32" width="22" height="22"
       style="border-radius:6px;flex-shrink:0;" aria-hidden="true">
    <rect width="32" height="32" rx="8" fill="#BE123C"/>
    <path d="M8 22c0-4.418 3.582-8 8-8s8 3.582 8 8" fill="#FDA4AF" stroke="#FDA4AF" stroke-width="1.5"/>
    <circle cx="16" cy="10" r="4" fill="#FDA4AF"/>
    <path d="M6 26h20" stroke="#F1F5F9" stroke-width="1.5" stroke-linecap="round"/>
    <path d="M10 26v-3a3 3 0 013-3h6a3 3 0 013 3v3" fill="#F1F5F9" opacity="0.4"/>
  </svg>
  Continuar con Bolivia ID
</a>

Logo mark — chapaco-id-mark.png

Disponible en https://tarija.id/brand/chapaco-id-mark.png

Descargar

Integración con Cursor (MCP)

Probá OAuth directamente desde el IDE

Configuración de MCP

1Abrí el Dev Portal y creá una app de prueba.
2Copiá client_id y client_secret.
3Agregá el bloque JSON de la derecha en tu .cursor/mcp.json.
4Reiniciá Cursor para cargar el servidor MCP.

Más detalles en docs/oauth-mcp.md

.cursor/mcp.jsonjson

{
  "mcpServers": {
    "tarija-id-oauth": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-everything"
      ],
      "env": {
        "TARIJA_ID_APP_URL": "https://boliviaid.com",
        "TARIJA_ID_CLIENT_ID": "tic_YOUR_CLIENT_ID",
        "TARIJA_ID_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "TARIJA_ID_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}

// 1. Redirigir al ciudadano const params = new URLSearchParams({ client_id: "tic_...", redirect_uri: "https://miapp.com/callback", scope: "profile email", state: crypto.randomUUID(), }); window.location.href = `https://boliviaid.com/oauth/authorize?${params}`; // 2. En tu callback — intercambiar código const tokenRes = await fetch("https://boliviaid.com/api/oauth/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ grant_type: "authorization_code", code, client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, }), }); const { access_token } = await tokenRes.json(); // 3. UserInfo const profile = await fetch("https://boliviaid.com/api/oauth/userinfo", { headers: { Authorization: `Bearer ${access_token}` }, }).then((r) => r.json());

# Intercambiar código por token curl -X POST https://boliviaid.com/api/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE" \ -d "client_id=tic_..." \ -d "client_secret=SECRET" \ -d "redirect_uri=https://miapp.com/callback" # Consultar perfil curl https://boliviaid.com/api/oauth/userinfo \ -H "Authorization: Bearer ACCESS_TOKEN"

Reglas de Redirect URIs: • Coincidencia exacta (sin wildcards, sin path traversal) • Deben usar HTTPS en producción • Para desarrollo local: http://localhost:3000/callback • Se configuran en el Dev Portal y se validan en cada request

# Enviar notificación al ciudadano (máx. 3/hora, intervalo 10 min) curl -X POST https://boliviaid.com/api/oauth/notify \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"titulo":"Tu pedido fue aceptado","cuerpo":"El profesional confirmó tu consulta.","href":"/mis-pedidos","idempotenciaKey":"order-123-msg"}'

// Copia el archivo chapaco-id-button.tsx desde // github.com/tarija-id/tarija-id → components/auth/ import { ChapacoIdButton } from "@/components/auth/chapaco-id-button"; <ChapacoIdButton clientId="tu_client_id" redirectUri="https://tuapp.com/callback" scope="profile email" />

<a href="https://tarija.id/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=profile&response_type=code" style="display:inline-flex;align-items:center;gap:10px;padding:10px 18px; background:#0f172a;color:#fff;border-radius:14px;text-decoration:none; font-family:system-ui;font-size:14px;font-weight:600;"> <svg viewBox="0 0 32 32" width="22" height="22" style="border-radius:6px;flex-shrink:0;" aria-hidden="true"> <rect width="32" height="32" rx="8" fill="#BE123C"/> <path d="M8 22c0-4.418 3.582-8 8-8s8 3.582 8 8" fill="#FDA4AF" stroke="#FDA4AF" stroke-width="1.5"/> <circle cx="16" cy="10" r="4" fill="#FDA4AF"/> <path d="M6 26h20" stroke="#F1F5F9" stroke-width="1.5" stroke-linecap="round"/> <path d="M10 26v-3a3 3 0 013-3h6a3 3 0 013 3v3" fill="#F1F5F9" opacity="0.4"/> </svg> Continuar con Bolivia ID </a>

{ "mcpServers": { "tarija-id-oauth": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-everything" ], "env": { "TARIJA_ID_APP_URL": "https://boliviaid.com", "TARIJA_ID_CLIENT_ID": "tic_YOUR_CLIENT_ID", "TARIJA_ID_CLIENT_SECRET": "YOUR_CLIENT_SECRET", "TARIJA_ID_REDIRECT_URI": "http://localhost:3000/callback" } } } }