JWKS endpoint

A JWKS (JSON Web Key Set) endpoint publishes the public key that matches the private key you sign Partner JWTs with. AIR fetches it to check every Partner JWT, so credential calls fail until it is live and registered.

Operation	JWKS required?
`issueCredential` and `verifyCredential` (SDK)	Yes
Direct issuance (AIR API)	Yes
`login` with a Partner JWT (Flutter, Custom Auth, or optionally on Web)	Yes
`login` without a Partner JWT (Web)	No

How AIR uses your JWKS

If AIR cannot fetch your JWKS, or no key in it matches the JWT’s kid, the request fails with 401.

Step 1: Implement the route

This Next.js route is the one used by every issuer and verifier app in air-examples. It converts your public key from PEM to JWK with jose and sets kid to your Partner ID.

app/api/.well-known/jwks/route.ts

import { NextResponse } from "next/server";
import * as jose from "jose";

export async function GET() {
  try {
    const publicKeyPEM = `-----BEGIN PUBLIC KEY-----\n${process.env.PARTNER_PUBLIC_KEY!}\n-----END PUBLIC KEY-----`;
    const publicKey = await jose.importSPKI(publicKeyPEM, process.env.SIGNING_ALGORITHM!);
    const jwk = await jose.exportJWK(publicKey);

    return NextResponse.json(
      {
        keys: [
          {
            ...jwk,
            kid: process.env.NEXT_PUBLIC_PARTNER_ID!,
            use: "sig",
            alg: process.env.SIGNING_ALGORITHM!,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "public, max-age=3600",
        },
      },
    );
  } catch {
    return NextResponse.json({ error: "Failed to generate JWKS" }, { status: 500 });
  }
}

Required environment variables (server-side only — never expose PARTNER_PRIVATE_KEY):

Variable	Used for
`PARTNER_PUBLIC_KEY`	The base64 body of your RS256 or ES256 public key (between the BEGIN/END markers).
`PARTNER_PRIVATE_KEY`	The matching private key used to sign your Partner JWT. Server-only.
`SIGNING_ALGORITHM`	`RS256` or `ES256`. Must match the key type.
`NEXT_PUBLIC_PARTNER_ID`	Your Partner ID. Used as `kid` so the JWKS key matches the JWT header.

Generate the key pair as described in SDK authentication.

Step 2: Register the URL in the Dashboard

Open the Developer Dashboard.
Go to Account → General Settings.
Paste the full HTTPS URL into JWKS URL, for example https://app.example.com/api/.well-known/jwks, and save.

AIR fetches exactly this URL, with no path discovery or fallback. Register the path your app actually serves: /api/.well-known/jwks for the route above, or whatever route you defined yourself. Each Partner ID has one JWKS URL. If your issuer and verifier apps share a Partner ID, register one JWKS and sign all Partner JWTs with a kid it contains. If you need separate JWKS per service, request a second Partner ID.

Step 3: Match the `kid`

The kid in each Partner JWT header must appear as a keys[].kid in your JWKS. The examples use your Partner ID for both. If you use another convention, such as key-rotation IDs, the rule is the same. Check the endpoint before you call the SDK:

curl https://app.example.com/api/.well-known/jwks
# → { "keys": [ { "kty": "RSA", "kid": "<your-partner-id>", "alg": "RS256", ... } ] }

Local development (HTTPS tunnel)

To test any AIR Kit flow locally, always run your app behind an HTTPS tunnel. AIR Kit only runs on HTTPS origins whitelisted under Account → Domains.

Start your dev server, then expose it over public HTTPS with a tunnel (examples below).
Whitelist the tunnel domain, such as https://abc123.ngrok.app, under Account → Domains. AIR Kit refuses to load on any origin that is not whitelisted there.
Register the tunnel’s JWKS URL as your JWKS URL.
Open your app at the tunnel URL and test from there.

Most free tunnels assign a new URL each time they restart. When the URL changes, whitelist the new domain, remove the old one (the list holds up to 3 domains), and update the JWKS URL. A reserved or static tunnel domain avoids this. If you also tunnel an issuer backend, its host is part of your issuer DID; see Issuer backend hosting.

ngrok
cloudflared

ngrok http 3000
# → forwarding https://abc123.ngrok.app -> http://localhost:3000

Whitelist https://abc123.ngrok.app under Account → Domains, register https://abc123.ngrok.app/api/.well-known/jwks as the JWKS URL, and open https://abc123.ngrok.app.

cloudflared tunnel --url http://localhost:3000
# → trycloudflare https://random-words.trycloudflare.com

Whitelist https://random-words.trycloudflare.com under Account → Domains, register https://random-words.trycloudflare.com/api/.well-known/jwks as the JWKS URL, and open https://random-words.trycloudflare.com.

Troubleshooting

If AIR still rejects your Partner JWT, see Common issues:

JWKS endpoint unreachable — AIR cannot fetch your URL.
Invalid signature — JWKS reachable but signature does not validate.
kid not found — JWT header kid is not present in keys[].

Overview

Quickstarts

Additional

Launch

About Authentication

Customization Options

Recipes

How AIR uses your JWKS

Step 1: Implement the route

Step 2: Register the URL in the Dashboard

Step 3: Match the `kid`

Local development (HTTPS tunnel)

Troubleshooting

​How AIR uses your JWKS

​Step 1: Implement the route

​Step 2: Register the URL in the Dashboard

​Step 3: Match the kid

​Local development (HTTPS tunnel)

​Troubleshooting

How AIR uses your JWKS

Step 1: Implement the route

Step 2: Register the URL in the Dashboard

Step 3: Match the `kid`

Local development (HTTPS tunnel)

Troubleshooting