JWTKit

The JWTKeyCollection is an actor used to manage signing keys and keysets. It is responsible for both signing new tokens and verifying existing ones. Because it is an actor, all its methods are async and must be awaited to ensure thread safety.

To use it, initialize a collection and add keys using algorithm-specific methods (e.g., add(hmac:...), add(ecdsa:...)). If you provide a kid (Key ID), JWTKit will use that ID to select the correct key during verification based on the kid in the JWT header. If no kid is provided, the key is treated as the default.

Warning: If you add multiple keys without a kid, only the last one will be stored; previous ones will be overwritten.

import JWTKit

// Signs and verifies JWTs
let keys = JWTKeyCollection()

To sign a token, first define a payload type that conforms to JWTPayload. Each property in your struct represents a claim. You must implement the verify(using:) method to handle claim validation (e.g., checking expiration).

Once your payload is ready, use JWTKeyCollection.sign(_:kid:) to generate the signed JWT string.

struct ExamplePayload: JWTPayload {
    var sub: SubjectClaim
    var exp: ExpirationClaim
    var admin: BoolClaim

    func verify(using key: some JWTAlgorithm) throws {
        try self.exp.verifyNotExpired()
    }
}

let payload = ExamplePayload(
    subject: "vapor",
    expiration: .init(value: .distantFuture),
    isAdmin: true
)

// Sign the payload, returning the JWT as String
let jwt = try await keys.sign(payload, kid: "my-key")

To verify a token, you must provide the type that the payload should be decoded into. Use JWTKeyCollection.verify(_:as:). This method parses the JWT, verifies the signature using the keys in the collection, and returns the decoded payload on success.

let exampleJWT = "..."

// Parse the JWT, verify its signature and decode its content
let payload = try await keys.verify(exampleJWT, as: ExamplePayload.self)
print(payload)

You can install JWTKit by manually adding it to your Package.swift file or by using the SwiftPM command line.

Manual Configuration

Add the following to your Package.swift:

dependencies: [
    .package(url: "https://github.com/vapor/jwt-kit.git", from: "5.0.0")
],
targets: [
    .target(
        name: "MyTarget",
        dependencies: [
            .product(name: "JWTKit", package: "jwt-kit"),
        ]),
]

CLI Installation

Run these commands in your project root, replacing MyTarget with your actual target name:

swift package add-dependency https://github.com/vapor/jwt-kit.git --from 5.0.0
swift package add-target-dependency JWTKit MyTarget --package jwt-kit

If you do not need to change the parsing/serialization logic itself, but only need to customize how JSON is encoded or decoded (e.g., changing dateEncodingStrategy), use DefaultJWTParser and DefaultJWTSerializer to wrap your custom JSONDecoder and JSONEncoder.

let encoder = JSONEncoder()
encoder.dateEncodingStrategy = .iso8601
let decoder = JSONDecoder() 
decoder.dateDecodingStrategy = .iso8601

let parser = DefaultJWTParser(jsonDecoder: decoder)
let serializer = DefaultJWTSerializer(jsonEncoder: encoder)

let keyCollection = await JWTKeyCollection().add(
    hmac: "secret",
    digestAlgorithm: .sha256,
    parser: parser, 
    serializer: serializer
)

MLDSA is a post-quantum signature scheme. Note: MLDSA requires macOS 26+. You can initialize an MLDSA key using a seed representation and add it to the collection.

// Initialize an MLDSA key with its seed
let seedRepresentation = Data("...".utf8)
let privateKey = try MLDSA87PrivateKey(seedRepresentation: seedRepresentation)

// Add private key to the key collection
await keys.add(mldsa: privateKey)

You can import a full JSON Web Key Set (JWKS) into a JWTKeyCollection using the add(jwksJSON:) method. This is useful for integrating with providers like Apple that host public keys at a specific URL. JWTKit will automatically use the kid from the JWT header to select the appropriate key from the set during verification.

let json = """
{
    "keys": [
        {"kty": "RSA", "alg": "RS256", "kid": "a", "n": "...", "e": "AQAB"},
        {"kty": "RSA", "alg": "RS512", "kid": "b", "n": "...", "e": "AQAB"}
    ]
}
"""

// Create key collection and add JWKS
let keys = try await JWTKeyCollection().add(jwksJSON: json)

ECDSA is an asymmetric algorithm. You can initialize an ECDSA key using a public PEM string and then add it to the collection using add(ecdsa:).

let ecdsaPublicKey = "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"

// Initialize an ECDSA key with public pem.
let key = try ES256PublicKey(pem: ecdsaPublicKey)

// Add ECDSA with SHA-256 algorithm
await keys.add(ecdsa: key)

EdDSA (specifically Ed25519) is an asymmetric algorithm. You can create keys using their coordinates and add either the public or private key to the collection.

// Initialize an EdDSA key with public PEM
let publicKey = try EdDSA.PublicKey(x: "...", curve: .ed25519)

// Initialize an EdDSA key with private PEM
let privateKey = try EdDSA.PrivateKey(x: "...", d: "...", curve: .ed25519)

// Add public key to the key collection
await keys.add(eddsa: publicKey)

// Add private key to the key collection
await keys.add(eddsa: privateKey)

HMAC is a symmetric algorithm where the same key is used for both signing and verification. Use the add(hmac:digestAlgorithm:kid:) method to register an HMAC key.

// Registers an HS256 (HMAC-SHA-256) signer with a key identifier.
await keys.add(hmac: "secret", digestAlgorithm: .sha256, kid: "my-key")