User authentication

A user token identifies an individual end-user within your tenant. It is layered on top of your Entra token via a separate X-User-Token header — the two tokens are independent and serve different purposes: the Entra token proves your tenant identity, the user token proves which of your users is acting.

User tokens are RS256-signed JWTs issued by the partner (you), verified by Yieldforce via your published JWKS endpoint.

When you need it

Every endpoint under /v1/partner/end_users/{external_id}/* requires a user token. This includes get-end-user, list portfolios, create portfolio, wallet balance, list transactions, deposit, and withdraw.

Endpoints that operate at the tenant level — list pools (GET /v1/partner/pools), create end-user (POST /v1/partner/end_users), and delete end-user (DELETE /v1/partner/end_users/{external_id}) — require only the Entra token.

JWKS endpoint requirements

Before Yieldforce can validate any partner JWT, your JWKS endpoint must be reachable and correctly structured.

• HTTPS in production. HTTP is only acceptable during local development using a tunnel such as ngrok. Your registered jwksUrl must use https:// in staging and production environments.
• RFC 5785 path. Serve the JWK Set at /.well-known/jwks.json on a root-level domain (e.g., https://your-domain/.well-known/jwks.json). The demo implements this at src/app/.well-known/jwks.json/route.ts.
• JWK Set format. The response body must be a JSON object with a keys array. Each key object must include kid, kty, n, e, use, and alg.
• No authentication required. The endpoint must be publicly accessible — Yieldforce fetches it without any credentials.
• Caching is fine. The demo sets Cache-Control: public, max-age=3600. Yieldforce's JWKS client also caches keys per kid for 24 hours. This means key rotation works without coordination: as long as you keep old kid values in your JWKS response until all JWTs signed with them expire, validation continues uninterrupted. See Key rotation below.

Required JWT claims

JWT header

Minting (TS example)

The following snippet mirrors src/lib/jwt.ts exactly, using the jose library:

import { SignJWT, importPKCS8 } from 'jose';
 
const KID = 'partner-demo-key-1'; // must match a kid in your JWKS response
 
export async function mintPartnerJwt(userId: string): Promise<string> {
  const privatePem = process.env.PARTNER_PRIVATE_KEY_PEM!;
  const issuer = process.env.PARTNER_ISSUER ?? 'http://localhost:3500';
  const audience = process.env.PARTNER_AUDIENCE ?? 'api://yieldforce';
  const ttl = Number.parseInt(process.env.PARTNER_JWT_TTL_SECONDS ?? '3600', 10);
 
  const privateKey = await importPKCS8(privatePem, 'RS256');
 
  return new SignJWT({})
    .setProtectedHeader({ alg: 'RS256', kid: KID, typ: 'JWT' })
    .setSubject(userId) // the end-user's external_id
    .setIssuer(issuer) // must match your registered JWKS issuer URL
    .setAudience(audience) // must be 'api://yieldforce'
    .setIssuedAt()
    .setExpirationTime(`${ttl}s`)
    .sign(privateKey);
}

privatePem is the PKCS#8 PEM of your RSA-2048 private key. In the demo this is loaded from PARTNER_PRIVATE_KEY_PEM env var or from ./.keys/private.pem — see src/lib/keys.ts for the load/generate logic.

How Yieldforce validates

The backend caches public keys per kid for 24 hours. Signature verification uses RS256 exclusively — the algorithm is enforced on the backend and is not read from the token header.

Sending the JWT

A correct user-scoped request includes both:

const res = await fetch(`${baseUrl}/v1/partner/end_users/${externalId}/portfolios`, {
  headers: {
    Authorization: `Bearer ${entraToken}`, // Entra — tenant identity
    'X-User-Token': partnerJwt, // user-scoped — user identity
    'Content-Type': 'application/json',
  },
});

Key rotation

Rotate your signing key without any downtime or coordination with Yieldforce:

1. Generate a new RSA-2048 keypair with a new kid (e.g., partner-key-2).
2. Add the new public key (with the new kid) to your JWKS endpoint response. Keep the old key in the response — do not remove it yet.
3. Start minting new JWTs using the new private key and kid.
4. Wait until all JWTs signed with the old kid have expired (typically 1 hour after you switched over, matching your exp TTL).
5. Remove the old kid from your JWKS endpoint response.

Yieldforce's JWKS client caches keys per kid for 24 hours. When a token arrives with a kid not found in the cache, the client re-fetches your JWKS endpoint immediately. As long as the old key remains in your JWKS response during the transition window, validation continues uninterrupted for in-flight tokens.

Common errors