Overview

Relevant source files

• JWTDecode/JWT.swift
• JWTDecode/JWTDecodeError.swift
• README.md

JWTDecode.swift is a lightweight Swift library for decoding JSON Web Tokens (JWTs) on Apple platforms. The library provides a simple, type-safe API for extracting header information, registered claims, and custom claims from JWT strings without performing cryptographic validation.

Important: This library decodes JWT structure and content but does not perform signature validation, expiration checks, or any cryptographic verification. It accepts any well-formed JWT that can be Base64URL-decoded. For information about the library's non-validation policy and security considerations, see Library Scope and Non-Validation Policy.

For installation instructions and quick start examples, see Getting Started.

Sources: README.md1-11

---

Library Purpose and Capabilities

JWTDecode.swift serves a single, focused purpose: parsing JWT tokens into strongly-typed Swift objects. The library extracts the three components of a JWT (header, body, signature) and provides convenient accessors for:

• Standard registered claims (exp, iss, sub, aud, iat, nbf, jti)
• Custom claims with type-safe conversion to primitive types (String, Int, Double, Date, Bool, Array)
• Complex claims decoded to Decodable types
• Token expiration status checks (convenience methods, not cryptographic validation)

The library is fully compatible with Swift 6's concurrency features, with all public types conforming to Sendable for safe usage across concurrency boundaries.

Sources: README.md70-161

---

Core Architecture Overview

The library's architecture consists of three primary components that form a simple, linear decoding pipeline:

Decoding Pipeline:

1. Entry Point: decode(jwt:) function accepts a JWT string and performs Base64URL decoding and JSON parsing
2. Token Representation: Returns an object conforming to the JWT protocol with structured access to token parts
3. Claim Access: Individual claims are accessed through the Claim type with type-safe conversion methods
4. Error Handling: Malformed tokens throw JWTDecodeError with specific failure cases

For detailed information about each component:

• Decoding implementation: JWT Decoding Implementation
• JWT protocol and token structure: JWT Protocol and Token Structure
• Claim type system: Claim Type System and Access Patterns
• Error handling: Error Handling

Sources: README.md84-171 JWTDecode/JWT.swift1-90 JWTDecode/JWTDecodeError.swift1-42

---

Public API Surface and Code Entities

The following diagram maps the complete public API surface to actual code entities in the codebase:

Key Code Entities:

Entity	Type	Location	Purpose
decode(jwt:)	Function	JWTDecode.swift	Entry point for decoding JWT strings
JWT	Protocol	JWT.swift10	Token abstraction with claim accessors
Claim	Struct	Claim.swift	Type-safe claim value wrapper
JWTDecodeError	Enum	JWTDecodeError.swift4	Decoding error cases

Sources: JWTDecode/JWT.swift10-89 JWTDecode/JWTDecodeError.swift4-42 README.md84-161

---

Platform Support

JWTDecode.swift provides comprehensive support across all Apple platforms:

Platform	Minimum Version
iOS	14.0+
macOS	11.0+
tvOS	14.0+
watchOS	7.0+
visionOS	1.0+

Development Requirements:

• Xcode 16.x or later
• Swift 6.0 or later

The library follows a rolling support policy where only the last four major versions of each platform are supported. Dropping support for older platform versions is not considered a breaking change and may occur in minor releases. For detailed information about the support policy, see the README Support Policy section

For information about multi-platform build configuration and targets, see Multi-Platform Support.

Sources: README.md28-32 README.md173-192

---

Distribution and Integration

JWTDecode.swift is distributed through three primary package managers, enabling flexible integration into iOS and macOS projects:

Quick Integration:

For detailed installation instructions and integration guides:

• Swift Package Manager: Swift Package Manager Integration
• CocoaPods: CocoaPods Integration
• Carthage: Carthage Support
• Complete distribution overview: Package Distribution and Integration

Sources: README.md34-68

---

Swift Concurrency Support

All public types in JWTDecode.swift conform to the Sendable protocol, enabling safe usage in Swift 6's structured concurrency contexts:

The Sendable conformance was introduced in version 4.0 as part of the library's Swift 6 compatibility effort. All dictionary values use any Sendable as the value type, ensuring type-safe concurrent access to JWT data.

For migration information from v3 to v4, see Migration Guides.

Sources: README.md74-76 JWTDecode/JWT.swift10-16 JWTDecode/JWTDecodeError.swift4

---

Typical Usage Flow

The following diagram illustrates a typical usage pattern from token receipt to claim extraction:

Typical Usage Pattern:

1. Decode: Call decode(jwt:) with token string
2. Access Standard Claims: Use convenience properties (jwt.subject, jwt.expiresAt)
3. Access Custom Claims: Use subscript syntax (jwt["custom_claim"])
4. Convert Types: Use type-safe accessors (.string, .integer, .date)
5. Handle Errors: Catch JWTDecodeError for malformed tokens

For detailed code examples, see Getting Started. For complete API documentation, see the API documentation

Sources: README.md84-171

---

Development and Quality Infrastructure

JWTDecode.swift includes comprehensive automation infrastructure for development, testing, and release management:

System	Purpose	Key Components
CI/CD	Automated testing and releases	GitHub Actions, fastlane
Testing	Multi-platform test execution	Quick, Nimble, platform-specific test targets
Code Quality	Linting and coverage tracking	SwiftLint, Slather, Codecov
Documentation	API docs and guides	DocC, README, migration guides
Distribution	Package publishing	CocoaPods trunk, SPM registry

The development workflow is orchestrated by GitHub Actions, which runs parallel test suites across all supported platforms, validates package configurations, and enforces code quality standards. The fastlane automation handles release tasks including version tagging, podspec publishing, and documentation generation.

For detailed information:

• CI/CD architecture: CI/CD and Automation
• Testing infrastructure: Testing Infrastructure
• Contributing guidelines: Contributing and Maintenance

Sources: README.md4-5 README.md193-209

---

Related Resources

• API Documentation: https
• Auth0 Documentation: https
• JWT Specification: JWT.io
• Source Repository: github.com/auth0/JWTDecode.swift
• Issue Tracker: GitHub Issues

Sources: README.md15-21 JWTDecode/JWT.swift7-9