Would love to see a type for decoded jwt

[uap-dev]

So far enjoying stytch so thank you for the hard work.

A few things I have noticed. The shape of the decoded JWT is not typed, cannot seem to find in the B2B lib. I decided to make my own, but running into some interface mismatches with what I would expect.

// stytch-decoded-session-jwt.ts
import { MemberSession } from "stytch";

export interface DecodedStytchSessionJwt {
  // Custom Claims, Configured on https://stytch.com/dashboard/custom-claim-templates
  memberId: string;
  orgId: string;
  emailAddress: string;

  // Reserved
  aud: string[];
  exp: number;
  iat: number;
  iss: string;
  nbf: number;
  sub: string;

  // Organization details
  "https://stytch.com/organization": {
    organization_id: string;
    slug: string;
  };
  // Session Object
  "https://stytch.com/session": MemberSession;
}

Here is an example decoded JWT that I received from a B2B auth.

{
  "aud": [
    "[REDACTED]"
  ],
  "emailAddress": "[REDACTED]",
  "exp": "[REDACTED]",
  "https://stytch.com/organization": {
    "organization_id": "[REDACTED]",
    "slug": "[REDACTED]"
  },
  "https://stytch.com/session": {
    "id": "[REDACTED]",
    "started_at": "2025-01-18T20:52:01Z",
    "last_accessed_at": "2025-01-18T20:52:01Z",
    "expires_at": "2025-01-18T21:52:01Z",
    "attributes": {
      "user_agent": "[REDACTED]",
      "ip_address": "[REDACTED]"
    },
    "authentication_factors": [
      {
        "type": "oauth",
        "delivery_method": "oauth_google",
        "last_authenticated_at": "2025-01-18T20:51:45Z",
        "google_oauth_factor": {
          "id": "[REDACTED]",
          "email_id": "[REDACTED]",
          "provider_subject": "[REDACTED]"
        }
      }
    ],
    "roles": [
      "stytch_member",
      "stytch_admin"
    ]
  },
  "iat": "[REDACTED]",
  "iss": "[REDACTED]",
  "memberId": "[REDACTED]",
  "nbf": "[REDACTED]",
  "orgId": "[REDACTED]",
  "orgSlug": null,
  "sub": "[REDACTED]"
}

Two issues:

• The decoded JWT type is opaque
• session_custom claims are not appearing as expected. The MemberSession suggests custom claims lives on a custom_claims field on the session object, whereas in the actual decoded JWT, the custom claims are flattened onto the decoded JWT object. No preference on where they live, but given that the jwt actually encodes the member session my expectation given the MemberSession type would be that they would live on the session object.

[max-stytch]

Hey @troutzen!

We provide a utility method - stytch.session.authenticateJwtLocal() - which handles validation and decoding of the JWT. The response of this method is typed. This method handles munging of the JWT data format back into the MemberSession data format - as they aren’t exactly 1-1.

Do you need anything in the underlying JWT that you are unable to get from the authenticateJwtLocal response?