Decodes a JSON Web Key (JWK) containing a private key into a signing key.

Use this for loading private keys from secure configuration or key management systems when implementing JWT signing services.

Security Considerations

• Only accept keys from trusted sources
• Store private keys in secure key management systems, never in code
• Only keep private keys in your auth service, they should never leave secure boundaries
• Rotate private keys regularly and have a key rotation strategy

Example

// Load private key from secure configuration (never hardcode!)
let private_jwk = load_from_secure_vault("jwt-signing-key")

case json.parse(private_jwk, sign_key.decoder()) {
  Ok(sign_key) -> {
    // Use to create signed JWTs
    encode(payload: [#("sub", json.string("user123"))],
           claims: [],
           key: sign_key)
  }
  Error(_) -> // Handle key loading error
}

🔐 Critical: Sign keys are the most important pieces of your security. Treat them accordingly.

Creates a symmetric HMAC-SHA256 signing key for JWT authentication.

This is the most commonly used algorithm for simple applications where you have a shared secret between your application and the service that will verify JWTs. The same key is used for both signing and verification.

Security Considerations

• The secret must be cryptographically random and at least 256 bits (32 bytes) long
• Keep the secret absolutely confidential - anyone with access can forge tokens
• Rotate secrets regularly and have a key rotation strategy
• Never store secrets in code or version control

Example

import gleam/crypto

// Generate a secure random secret
let secret = crypto.strong_random_bytes(32)
let assert Ok(key) = sign_key.hs256(secret)

// Use this key to sign JWTs
ywt.encode(payload: [#("sub", json.string("user123"))], claims: [], key: key)

⚠️ Warning: HMAC keys are symmetric - the same key signs and verifies tokens. This means every service that needs to verify tokens must have the secret, increasing the attack surface.

Creates a symmetric HMAC-SHA384 signing key for for JWT authentication.

Choose this over HS256 when you need additional security margins or your security policy requires SHA-384.

Security Considerations

• The secret must be cryptographically random and at least 384 bits (48 bytes) long
• Keep the secret absolutely confidential - anyone with access can forge tokens
• Rotate secrets regularly and have a key rotation strategy
• Never store secrets in code or version control

Example

import gleam/crypto

// Generate a secure random secret
let secret = crypto.strong_random_bytes(48)
let assert Ok(key) = sign_key.hs384(secret)

// Use this key to sign JWTs
ywt.encode(payload: [#("sub", json.string("user123"))], claims: [], key: key)

⚠️ Warning: HMAC keys are symmetric - the same key signs and verifies tokens. This means every service that needs to verify tokens must have the secret, increasing the attack surface.

Creates a symmetric HMAC-SHA512 signing key for JWT authentication.

This is the most commonly used algorithm for simple applications where you have a shared secret between your application and the service that will verify JWTs. The same key is used for both signing and verification.

Security Considerations

• The secret must be cryptographically random and at least 512 bits (64 bytes) long
• Keep the secret absolutely confidential - anyone with access can forge tokens
• Rotate secrets regularly and have a key rotation strategy
• Never store secrets in code or version control

Example

import gleam/crypto

// Generate a secure random secret
let secret = crypto.strong_random_bytes(64)
let assert Ok(key) = sign_key.hs512(secret)

// Use this key to sign JWTs
ywt.encode(payload: [#("sub", json.string("user123"))], claims: [], key: key)

⚠️ Warning: HMAC keys are symmetric - the same key signs and verifies tokens. This means every service that needs to verify tokens must have the secret, increasing the attack surface.

Extracts the key identifier from a signing key, if present.

This function retrieves the optional key identifier that was assigned to a key. Key identifiers are used for key selection during JWT verification.

Assigns a random key identifier to a signing key for key management and rotation.

This function generates a cryptographically random identifier and assigns it to the key’s id field. Key identifiers enable proper key selection during JWT verification and are essential for implementing key rotation strategies.

Usage

Use this when you need to uniquely identify keys for distribution, storage, or rotation purposes. The identifier will be included in JWT headers as the kid (Key ID) field, allowing verifiers to select the correct key.