JWKS & Discovery

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "zb-id-2026-01",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw...",
      "e": "AQAB"
    }
  ]
}

{
  "issuer": "https://id.zb.co.zw",
  "jwks_uri": "https://id.zb.co.zw/.well-known/jwks.json",
  "token_endpoint": "https://id.zb.co.zw/oauth/token",
  "introspection_endpoint": "https://id.zb.co.zw/oauth/introspect",
  "grant_types_supported": [
    "client_credentials"
  ],
  "response_types_supported": [
    "token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "banking:read",
    "banking:write",
    "lending:read",
    "lending:write",
    "insurance:read",
    "insurance:write",
    "wealth:read",
    "wealth:write",
    "admin:users",
    "admin:roles",
    "admin:clients"
  ]
}

import jwt
import requests
from jwt import PyJWKClient

ZB_ID_URL = 'https://id.zb.co.zw'
ZB_ID_ISSUER = ZB_ID_URL
JWKS_URL = f'{ZB_ID_URL}/.well-known/jwks.json'

# Create a JWKS client (caches keys automatically)
jwks_client = PyJWKClient(JWKS_URL)

def verify_token(token: str) -> dict:
    """Verify a ZB ID JWT and return its claims."""
    # Get the signing key from JWKS
    signing_key = jwks_client.get_signing_key_from_jwt(token)

    # Decode and verify the token
    claims = jwt.decode(
        token,
        signing_key.key,
        algorithms=['RS256'],
        issuer=ZB_ID_ISSUER,
        options={
            'verify_exp': True,
            'verify_iss': True,
            'verify_aud': False,
        }
    )

    return claims

def require_scope(token: str, scope: str) -> dict:
    """Verify a token and check for a required scope."""
    claims = verify_token(token)
    scopes = claims.get('scopes', [])

    if scope not in scopes:
        raise PermissionError(
            f'Token missing required scope: {scope}'
        )

    return claims

# Usage
try:
    claims = require_scope(token, 'banking:read')
    user_id = claims['sub']
    kyc_tier = claims.get('kycTier')
except jwt.ExpiredSignatureError:
    print('Token has expired')
except jwt.InvalidTokenError as e:
    print(f'Invalid token: {e}')
except PermissionError as e:
    print(f'Access denied: {e}')

import * as jose from 'jose'

const ZB_ID_URL =
  'https://id.zb.co.zw'
const ZB_ID_ISSUER = ZB_ID_URL
const JWKS_URL =
  `${ZB_ID_URL}/.well-known/jwks.json`

// Create a remote JWKS set (caches keys)
const JWKS = jose.createRemoteJWKSet(
  new URL(JWKS_URL)
)

async function verifyToken(token) {
  const { payload } = await jose.jwtVerify(
    token,
    JWKS,
    {
      issuer: ZB_ID_ISSUER,
      algorithms: ['RS256'],
    }
  )
  return payload
}

async function requireScope(token, scope) {
  const claims = await verifyToken(token)
  const scopes = claims.scopes || []

  if (!scopes.includes(scope)) {
    throw new Error(
      `Token missing required scope: ${scope}`
    )
  }

  return claims
}

// Usage in Express
async function authMiddleware(scope) {
  return async (req, res, next) => {
    const token = req.headers.authorization
      ?.replace('Bearer ', '')

    if (!token) {
      return res.status(401).json({
        result: 'failed',
        message: 'No token provided',
      })
    }

    try {
      const claims = await requireScope(
        token,
        scope
      )
      req.userId = claims.sub
      req.scopes = claims.scopes
      req.kycTier = claims.kycTier
      next()
    } catch (err) {
      if (err.code === 'ERR_JWT_EXPIRED') {
        return res.status(401).json({
          result: 'failed',
          message: 'Token has expired',
        })
      }
      return res.status(403).json({
        result: 'failed',
        message: err.message,
      })
    }
  }
}

// Apply to routes
app.get(
  '/accounts/:id',
  await authMiddleware('banking:read'),
  (req, res) => {
    // req.userId and req.scopes are available
  }
)