> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/modularity/jwt/key-management.md).

# Key Management

The key registry lets you declare keys once in module configuration and reference them by name throughout your application. Keeping secrets in configuration (or environment variables) makes [key rotation](/boxlang-framework/modularity/jwt/key-rotation.md), auditing, and secret-manager integration far easier than embedding keys in code.

## Defining Keys

Keys live in the `keys` setting of your `ModuleConfig.bx`:

```javascript
settings = {
    keys : {

        // HMAC secret — supports ${env.VAR} placeholder substitution
        "api-signing" : {
            algorithm : "HS256",
            secret    : "${env.JWT_HMAC_SECRET}"
        },

        // RSA key pair (PEM file paths or inline PEM strings)
        "api-rsa" : {
            algorithm  : "RS256",
            privateKey : "/etc/keys/api-private.pem",
            publicKey  : "/etc/keys/api-public.pem"
        },

        // Public-only key for verifying third-party tokens
        "partner-public" : {
            algorithm : "RS256",
            publicKey : "/etc/keys/partner-public.pem"
        },

        // JWK (JSON Web Key) defined inline
        "oidc-verify" : {
            algorithm : "RS256",
            jwk       : { kty: "RSA", n: "...", e: "AQAB" }
        }
    }
}
```

The registry is parsed once at module startup. Every entry can supply any combination of `secret`, `privateKey`, `publicKey`, and `jwk` — the module picks whichever the operation requires.

## Using Named Keys

Pass the key's name in place of raw key material. The algorithm is resolved from the key metadata, so you can omit it too:

```javascript
token   = jwtCreate( { sub: "u1" }, "api-signing" );
payload = jwtVerify( token, "api-signing" );
```

## Module-Wide Defaults

Set `defaultSigningKey` / `defaultVerifyKey` (and the encryption equivalents) to drop the key argument entirely:

```javascript
settings = {
    keys              : { "app" : { algorithm: "HS256", secret: "${env.JWT_SECRET}" } },
    defaultSigningKey : "app",
    defaultVerifyKey  : "app"
}
```

```javascript
token   = jwtCreate( { sub: "u1" } );
payload = jwtVerify( token );
```

See [Configuration](/boxlang-framework/modularity/jwt/configuration.md) for the full list of default settings.

## Runtime Key Management

For dynamic key sources (KMS, Vault, rotating service accounts) you can manipulate the registry at runtime through `JWTService`:

```javascript
jwtService = getBoxContext().getRuntime().getGlobalService( "JWTService" );

// Register
jwtService.registerKey( "session-key", {
    algorithm : "HS256",
    secret    : generateSecureKey()
} );

// Inspect
names  = jwtService.getKeyNames();
hasKey = jwtService.hasKey( "session-key" );

// Remove
jwtService.removeKey( "session-key" );
```

## Picking the Right Key Type

| Use case                                        | Recommended                                                                                    |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Two services you own                            | HMAC (`HS256`) — shortest setup, fastest                                                       |
| Public consumers verifying your tokens          | RSA or EC (`RS256` / `ES256`) — distribute public key only                                     |
| Verifying third-party / OIDC tokens             | Public-only RSA/EC entry, or a JWK fetched from the issuer                                     |
| Confidential payloads at rest in client storage | RSA-OAEP for JWE — see [Encryption (JWE)](/boxlang-framework/modularity/jwt/encryption-jwe.md) |

## Related

* [Configuration](/boxlang-framework/modularity/jwt/configuration.md) — all settings reference
* [Key Rotation](/boxlang-framework/modularity/jwt/key-rotation.md)
* [Security Best Practices](/boxlang-framework/modularity/jwt/security-best-practices.md)
* [JWTGenerateSecret()](/boxlang-framework/modularity/jwt/reference/built-in-functions/jwtgeneratesecret.md)
* [JWTGenerateKeyPair()](/boxlang-framework/modularity/jwt/reference/built-in-functions/jwtgeneratekeypair.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/jwt/key-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.