Powered by Redocly

JWT Issuer Roles

A JWT issuer role defines the claim constraints applied when a caller invokes the role's mint action. Different roles on the same issuer can mint JWTs with different shapes (subject, audiences, custom claims, TTL).

Authority to invoke mint is conferred by policies that grant the caller update on the role's mint action path; the role itself only constrains what the resulting JWT may contain.

Create a new jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
allowed-audiences
Array of strings

Glob patterns each requested 'aud' value must match (e.g. https://api.*.example.com). If empty and default-audiences is also empty, mint requests must either omit audiences (with require-audience=false) or be rejected.

default-audiences
Array of strings

Audiences used when the caller does not supply any. Must themselves satisfy allowed-audiences if that list is set.

require-audience
boolean
Default: true

If true, the resulting JWT must contain at least one audience (caller-supplied or from default-audiences). When false, JWTs without an aud claim are permitted.

subject-template
string

Template expanded to produce the 'sub' claim. Supports SYS_TENANT and (when minting under a user token) SYS_USERNAME. When set, the caller cannot override 'sub'. Example: "${SYS_TENANT}/${SYS_USERNAME}".

allowed-subject-patterns
Array of strings

Valid when: ../subject-template = ''

Glob patterns the caller-supplied 'sub' must match. Only consulted when subject-template is not set.

default-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL when the caller does not specify one. Falls back to the issuer's default-ttl when unset.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL when minting via this role. Capped by the issuer's max-ttl. Unset means the issuer cap applies.

algorithm
string <enumeration>
  • ES256
  • ES384
  • RS256
  • EdDSA

Pin the JWS algorithm. Must be compatible with the issuer's signing-key cipher. If omitted, the algorithm is derived from the cipher.

Array of objects

Claims always added to the resulting JWT. Template-expanded at mint time. The caller cannot override these.

Array of objects

Custom claims the caller may include in the mint request's extra-claims input.

required-claims
Array of strings

Names of claims that must appear in the final JWT. Each must be present as a fixed-claim or supplied via the mint request.

verbose-logging
boolean
Default: false

Enable verbose logging for mint attempts on this role. Useful for debugging which constraint rejected a request.

to (object) or sites (object) or deployments (object)
Default: "to"
Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles
Request samples 
name: reader
allowed-audiences:
  - https://api.example.com
  - https://api.*.example.com
default-audiences:
  - https://api.example.com
require-audience: true
subject-template: ${SYS_TENANT}/${SYS_USERNAME}
default-ttl: 15m
max-ttl: 1h
algorithm: ES256
fixed-claims:
  - name: tier
    value: gold
  - name: realm
    value: ${SYS_TENANT}
allowed-claims:
  - name: scope
    type: string-array
    allowed-values:
      - read:*
      - list:*
  - name: trace_id
    type: string
    allowed-values:
      - "*"
required-claims:
  - tier
verbose-logging: false
distribute:
  to: all

Retrieve the configuration of all jwt issuer roles

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

where
string

Retrieve only items matching the given expression.

See section where

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles
Response samples 
- name: reader
  allowed-audiences:
    - https://api.example.com
    - https://api.*.example.com
  default-audiences:
    - https://api.example.com
  require-audience: true
  subject-template: ${SYS_TENANT}/${SYS_USERNAME}
  default-ttl: 15m
  max-ttl: 1h
  algorithm: ES256
  fixed-claims:
    - name: tier
      value: gold
    - name: realm
      value: ${SYS_TENANT}
  allowed-claims:
    - name: scope
      type: string-array
      allowed-values:
        - read:*
        - list:*
    - name: trace_id
      type: string
      allowed-values:
        - "*"
  required-claims:
    - tier
  verbose-logging: false
  distribute:
    to: all

Update a jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
allowed-audiences
Array of strings

Glob patterns each requested 'aud' value must match (e.g. https://api.*.example.com). If empty and default-audiences is also empty, mint requests must either omit audiences (with require-audience=false) or be rejected.

default-audiences
Array of strings

Audiences used when the caller does not supply any. Must themselves satisfy allowed-audiences if that list is set.

require-audience
boolean
Default: true

If true, the resulting JWT must contain at least one audience (caller-supplied or from default-audiences). When false, JWTs without an aud claim are permitted.

subject-template
string

Template expanded to produce the 'sub' claim. Supports SYS_TENANT and (when minting under a user token) SYS_USERNAME. When set, the caller cannot override 'sub'. Example: "${SYS_TENANT}/${SYS_USERNAME}".

allowed-subject-patterns
Array of strings

Valid when: ../subject-template = ''

Glob patterns the caller-supplied 'sub' must match. Only consulted when subject-template is not set.

default-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL when the caller does not specify one. Falls back to the issuer's default-ttl when unset.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL when minting via this role. Capped by the issuer's max-ttl. Unset means the issuer cap applies.

algorithm
string <enumeration>
  • ES256
  • ES384
  • RS256
  • EdDSA

Pin the JWS algorithm. Must be compatible with the issuer's signing-key cipher. If omitted, the algorithm is derived from the cipher.

Array of objects

Claims always added to the resulting JWT. Template-expanded at mint time. The caller cannot override these.

Array of objects

Custom claims the caller may include in the mint request's extra-claims input.

required-claims
Array of strings

Names of claims that must appear in the final JWT. Each must be present as a fixed-claim or supplied via the mint request.

verbose-logging
boolean
Default: false

Enable verbose logging for mint attempts on this role. Useful for debugging which constraint rejected a request.

to (object) or sites (object) or deployments (object)
Default: "to"
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}
Request samples 
name: reader
allowed-audiences:
  - https://api.example.com
  - https://api.*.example.com
default-audiences:
  - https://api.example.com
require-audience: true
subject-template: ${SYS_TENANT}/${SYS_USERNAME}
default-ttl: 15m
max-ttl: 1h
algorithm: ES256
fixed-claims:
  - name: tier
    value: gold
  - name: realm
    value: ${SYS_TENANT}
allowed-claims:
  - name: scope
    type: string-array
    allowed-values:
      - read:*
      - list:*
  - name: trace_id
    type: string
    allowed-values:
      - "*"
required-claims:
  - tier
verbose-logging: false
distribute:
  to: all

Delete a jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}

Replace or create a new jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
allowed-audiences
Array of strings

Glob patterns each requested 'aud' value must match (e.g. https://api.*.example.com). If empty and default-audiences is also empty, mint requests must either omit audiences (with require-audience=false) or be rejected.

default-audiences
Array of strings

Audiences used when the caller does not supply any. Must themselves satisfy allowed-audiences if that list is set.

require-audience
boolean
Default: true

If true, the resulting JWT must contain at least one audience (caller-supplied or from default-audiences). When false, JWTs without an aud claim are permitted.

subject-template
string

Template expanded to produce the 'sub' claim. Supports SYS_TENANT and (when minting under a user token) SYS_USERNAME. When set, the caller cannot override 'sub'. Example: "${SYS_TENANT}/${SYS_USERNAME}".

allowed-subject-patterns
Array of strings

Valid when: ../subject-template = ''

Glob patterns the caller-supplied 'sub' must match. Only consulted when subject-template is not set.

default-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL when the caller does not specify one. Falls back to the issuer's default-ttl when unset.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL when minting via this role. Capped by the issuer's max-ttl. Unset means the issuer cap applies.

algorithm
string <enumeration>
  • ES256
  • ES384
  • RS256
  • EdDSA

Pin the JWS algorithm. Must be compatible with the issuer's signing-key cipher. If omitted, the algorithm is derived from the cipher.

Array of objects

Claims always added to the resulting JWT. Template-expanded at mint time. The caller cannot override these.

Array of objects

Custom claims the caller may include in the mint request's extra-claims input.

required-claims
Array of strings

Names of claims that must appear in the final JWT. Each must be present as a fixed-claim or supplied via the mint request.

verbose-logging
boolean
Default: false

Enable verbose logging for mint attempts on this role. Useful for debugging which constraint rejected a request.

to (object) or sites (object) or deployments (object)
Default: "to"
Responses
201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}
Request samples 
name: reader
allowed-audiences:
  - https://api.example.com
  - https://api.*.example.com
default-audiences:
  - https://api.example.com
require-audience: true
subject-template: ${SYS_TENANT}/${SYS_USERNAME}
default-ttl: 15m
max-ttl: 1h
algorithm: ES256
fixed-claims:
  - name: tier
    value: gold
  - name: realm
    value: ${SYS_TENANT}
allowed-claims:
  - name: scope
    type: string-array
    allowed-values:
      - read:*
      - list:*
  - name: trace_id
    type: string
    allowed-values:
      - "*"
required-claims:
  - tier
verbose-logging: false
distribute:
  to: all

Retrieve the configuration of a jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

where
string

Retrieve only items matching the given expression.

See section where

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}
Response samples 
name: reader
allowed-audiences:
  - https://api.example.com
  - https://api.*.example.com
default-audiences:
  - https://api.example.com
require-audience: true
subject-template: ${SYS_TENANT}/${SYS_USERNAME}
default-ttl: 15m
max-ttl: 1h
algorithm: ES256
fixed-claims:
  - name: tier
    value: gold
  - name: realm
    value: ${SYS_TENANT}
allowed-claims:
  - name: scope
    type: string-array
    allowed-values:
      - read:*
      - list:*
  - name: trace_id
    type: string
    allowed-values:
      - "*"
required-claims:
  - tier
verbose-logging: false
distribute:
  to: all

Retrieve the state of all jwt issuer roles

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

where
string

Retrieve only items matching the given expression.

See section where

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/jwt-issuers/{jwt-issuer-name}/roles
Response samples 
- name: reader
  allowed-audiences:
    - https://api.example.com
    - https://api.*.example.com
  default-audiences:
    - https://api.example.com
  require-audience: true
  subject-template: ${SYS_TENANT}/${SYS_USERNAME}
  default-ttl: 15m
  max-ttl: 1h
  algorithm: ES256
  fixed-claims:
    - name: tier
      value: gold
    - name: realm
      value: ${SYS_TENANT}
  allowed-claims:
    - name: scope
      type: string-array
      allowed-values:
        - read:*
        - list:*
    - name: trace_id
      type: string
      allowed-values:
        - "*"
  required-claims:
    - tier
  verbose-logging: false
  distribute:
    to: all
  distribution-status:
    to: all

Retrieve the state of a jwt issuer role

Constraints applied when minting through this issuer. Different roles can produce JWTs with different subject, audience, and claim shapes.

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

where
string

Retrieve only items matching the given expression.

See section where

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}
Response samples 
name: reader
allowed-audiences:
  - https://api.example.com
  - https://api.*.example.com
default-audiences:
  - https://api.example.com
require-audience: true
subject-template: ${SYS_TENANT}/${SYS_USERNAME}
default-ttl: 15m
max-ttl: 1h
algorithm: ES256
fixed-claims:
  - name: tier
    value: gold
  - name: realm
    value: ${SYS_TENANT}
allowed-claims:
  - name: scope
    type: string-array
    allowed-values:
      - read:*
      - list:*
  - name: trace_id
    type: string
    allowed-values:
      - "*"
required-claims:
  - tier
verbose-logging: false
distribute:
  to: all
distribution-status:
  to: all

Invoke the mint operation

Mint a JWT under the constraints of this role.

The TTL, audiences, subject, and extra claims supplied here are validated against the role's constraints. The resulting JWT carries the issuer's 'iss' claim, the kid of the active signing key version, and the algorithm derived from the signing key's cipher (or from the role's algorithm leaf, if pinned).

SecurityaccessToken
Request
path Parameters
jwt-issuer-name
required
string <name>

name of jwt-issuer

jwt-issuer-role-name
required
string <name>

name of jwt-issuer-role

Request Body schema:
audiences
Array of strings

Audiences for the resulting JWT. Each must match one of the role's allowed-audiences globs. When omitted, the role's default-audiences are used.

subject
string

Subject ('sub' claim). Ignored when the role pins subject-template; otherwise must match one of allowed-subject-patterns.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Requested TTL. Clamped to the role's max-ttl (which in turn is capped by the issuer's max-ttl).

extra-claims
string

JSON object literal of additional claims, e.g. {"role":"reader","tier":"gold"}. Each name must appear in the role's allowed-claims and each value must satisfy that entry's allowed-values glob list.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/jwt-issuers/{jwt-issuer-name}/roles/{jwt-issuer-role-name}/mint
Request samples 
audiences:
  - https://api.example.com
subject: acme/alice
ttl: 15m
extra-claims: "{\"scope\":[\"read:orders\",\"list:invoices\"],\"trace_id\":\"7c1a\"}"
Response samples 
jwt: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJpc3MiOiJodHRwczovL3N0cm9uZ2JveC5leGFtcGxlLmNvbS9qd3QvcGF5bWVudHMtYXBpIiwic3ViIjoiYWNtZS9hbGljZSIsImF1ZCI6WyJodHRwczovL2FwaS5leGFtcGxlLmNvbSJdLCJpYXQiOjE3MTAwMDAwMDAsImV4cCI6MTcxMDAwMDkwMCwidGllciI6ImdvbGQiLCJyZWFsbSI6ImFjbWUiLCJzY29wZSI6WyJyZWFkOm9yZGVycyIsImxpc3Q6aW52b2ljZXMiXSwidHJhY2VfaWQiOiI3YzFhIn0.signature
kid: "1"
issuer: https://strongbox.example.com/jwt/payments-api
subject: acme/alice
audiences:
  - https://api.example.com
expires: 2024-03-09T12:15:00.000000Z
➔ Next to JWT Issuers