JWTs

The AAM_Framework_Service_Jwts service provides a complete JWT (JSON Web Token) lifecycle management layer for AAM.

It supports:

• Issuing JWT access tokens
• Validating token integrity and expiration
• Revoking tokens
• Refreshing tokens
• Maintaining a per-user token registry
• Querying issued tokens
• Supporting symmetric and asymmetric signing algorithms

The service is designed specifically for user access levels and integrates tightly with WordPress user meta storage.

Definition

class AAM_Framework_Service_Jwts {

    public get_tokens() : array
    public get_token_by(mixed $search, string $claim = null) : array|WP_Error

    public issue(array $claims = [], array $settings = []) : array
    public validate(string $token) : bool|WP_Error
    public revoke(string $token) : bool
    public refresh(string $token) : array
    public reset() : bool

}

Service Scope

The JWT service can only operate within the context of a user access level.

Internally, the service validates this during initialization:

if ($access_level->type !== AAM_Framework_Type_AccessLevel::USER) {
    throw new LogicException(
        'The JWT service expects ONLY user access level'
    );
}

This means:

• Tokens are always associated with a WordPress user
• Token registries are stored per user
• All issued tokens include the user_id claim

Token Registry

AAM maintains a registry of revocable tokens in WordPress user meta.

Registry storage key is aam_jwt_registry

Registry entries may be stored as either:

[
    'jwt-token-string',
    'another-token'
]

or with metadata:

[
    [
        'token' => 'jwt-token-string',
        'description' => 'API integration token'
    ]
]

The registry is used for:

• Revocation support
• Token lookup
• Validation of revocable tokens
• Token administration

Issuing Tokens

public function issue(array $claims = [], array $settings = [])

Parameters

$claims

Custom JWT claims to include in the payload.

Example:

[
    'role' => 'api_client',
    'scope' => [
        'read', 
        'write'
    ]
]

$settings

Optional token behavior settings.

Supported settings:

TTL Handling

TTL can be defined either as:

Relative time string

[
    'ttl' => '+7 days'
]

Numeric seconds

[
    'ttl' => 3600
]

Internally numeric values are normalized into:

+3600 seconds

Invalid TTL values throw:

InvalidArgumentException('Invalid token ttl')

Default Claims

The service automatically injects several claims into every token.

Example payload:

{
  "jti": "5b4f6a2a-1b6e-4bdf-95b8-8393c9f7af12",
  "iat": 1777420000,
  "iss": "https://example.com",
  "exp": 1777506400,
  "user_id": 15,
  "revocable": true,
  "refreshable": false,
  "role": "api_client"
}

Claim Customization Hook

Before token generation, claims pass through:

apply_filters('aam_jwt_claims_filter', $claims)

Example:

add_filter('aam_jwt_claims_filter', function($claims) {
    $claims['environment'] = 'production';

    return $claims;
});

Example: Issue Token

$jwt_service = AAM::api()->jwts();

$result = $jwt_service->issue(
    [
        'scope' => ['read', 'write']
    ],
    [
        'ttl' => '+30 days',
        'refreshable' => true,
        'description' => 'Mobile App Token'
    ]
);

Example response:

[
    'token' => 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
    'claims' => [ ... ],
    'is_valid' => true
]

Validating Tokens

public function validate(string $token)

Return Types

Validation Flow

Validation occurs in two stages.

Stage 1 — Cryptographic Validation

The utility class verifies:

• JWT structure
• Supported algorithm
• Signature integrity
• nbf claim
• iat claim
• exp claim

Stage 2 — Registry Validation

If token claim:

'revocable' => true

then the token must exist in the registry.

Otherwise validation fails with:

RuntimeException('Unregistered token')

Example: Validate Token

$result = $jwt_service->validate($token);

if (is_wp_error($result)) {
    echo $result->get_error_message();
} else {
    echo 'Valid token';
}

Revoking Tokens

public function revoke(string $token)

Behavior

Revocation removes the token from the registry.

Only revocable tokens can be revoked.

Once revoked:

• Validation fails
• Refresh fails
• Registry lookup fails

Example

$jwt_service->revoke($token);

Possible error:

Provided token is not registered

Refreshing Tokens

public function refresh(string $token)

Requirements

The token must:

• Be valid
• Not be expired
• Have:

'refreshable' => true

Refresh Process

When refreshing:

1. Original token is validated
2. Claims are decoded
3. TTL duration is preserved
4. rat claim is added
5. New token is issued
6. Old token is revoked
7. New token is registered

Refresh Claim

Refreshed tokens receive:

'rat' => time()

This represents:

• Refresh-at timestamp

Example

$new_token = $jwt_service->refresh($old_token);

Listing Tokens

public function get_tokens()

Returns all tokens from the registry.

Each token is normalized into a consistent structure.

Response Structure

[
    [
        'token' => 'jwt-token',
        'claims' => [ ... ],
        'is_valid' => true,
        'description' => 'Optional label'
    ]
]

If token validation fails:

[
    'token' => 'jwt-token',
    'claims' => [ ... ],
    'is_valid' => false,
    'error' => 'Expired token'
]

Example

$tokens = $jwt_service->get_tokens();

Finding Tokens

public function get_token_by($search, $claim = null)

Lookup by Raw Token

$jwt_service->get_token_by($token);

Lookup by Claim

$jwt_service->get_token_by(15, 'user_id');

Example:

$jwt_service->get_token_by('api_client', 'role');

Return Structure

[
    'token' => 'jwt-token',
    'claims' => [ ... ],
    'is_valid' => true
]

Resetting Tokens

public function reset()

Deletes the entire registry for the current user. This effectively revokes all revocable tokens.

Example

$jwt_service->reset();

Supported Algorithms

The utility supports the following signing algorithms.

Configuration

Signing Algorithm

service.jwt.signing_algorithm

Default:

HS256

HMAC Secret

Used for symmetric algorithms.

service.jwt.signing_secret

Default:

SECURE_AUTH_KEY

Registry Size

Controls maximum stored revocable tokens.

service.jwt.registry_size

Default:

10

When exceeded:

• Oldest token is removed automatically

Default Expiration

service.jwt.expires_in

Default:

+24 hours

RSA / ECDSA Certificate Configuration

Asymmetric algorithms require certificate paths.

Private Key

service.jwt.private_cert_path

Optional passphrase:

service.jwt.private_cert_passphrase

Public Key

service.jwt.public_cert_path

Path Placeholder

Certificate paths may include:

{ABSPATH}

Example:

{ABSPATH}/certs/private.pem

Security Considerations

Revocable vs Non-Revocable Tokens

Revocable Tokens

Advantages:

• Can be invalidated
• Tracked in registry
• Safer for long-lived access

Disadvantages:

• Require database lookup
• Slightly slower validation

Non-Revocable Tokens

Advantages:

• Stateless validation
• Faster performance
• No database dependency

Disadvantages:

• Cannot be revoked before expiration

Recommended Practices

Use Short Expiration

Prefer:

'+15 minutes'

instead of:

'+365 days'

Use Refreshable Tokens Carefully

Refreshable tokens are useful for:

• Mobile applications
• SPA authentication
• API sessions

Avoid unlimited refresh loops.

Prefer Revocable Tokens

For administrative access and privileged integrations.

Protect Signing Keys

Never expose:

• HMAC secret
• Private RSA/ECDSA certificates

Use HTTPS

JWTs should never travel over unsecured HTTP connections.

Error Handling

Most public methods return either:

• Valid response
• WP_Error

Always validate responses.

Example:

$result = $jwt_service->validate($token);

if (is_wp_error($result)) {
    error_log($result->get_error_message());
}

Common Errors