Using the JWK Sets REST API

The JWK Sets REST API provides the ability to manage JWK sets used for various Intelligent Advisor services and purposes.

For the permissions required to access the JWK Sets REST API, see Role Permissions for Intelligent Advisor REST APIs.

Example GET a JWK set

This operation will discover what the active key's ID ("kid") is.

The GET request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token

An example response to this request would be:

{
    "purpose": "wd_access_token",
    "allowedKeyUse": "enc",
    "activeKeyID": "e663e54e-4bcb-422d-9082-163355d70777",
    "keys": {
        "links": [ ... ]
    },
    "links": [ ... ]
}

Example GET a JWK set key

This operation will retrieve the active key using it's kid.

The GET request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token/keys/e663e54e-4bcb-422d-9082-163355d70777

An example response to this request would be:

{
    "kid": "e663e54e-4bcb-422d-9082-163355d70777",
    "kty": "EC",
    "use": "enc",
    "crv": "P-256",
    "x": "ny6tBcdL0F7uB7_VhsXkiqCMvlZsB0LspbztM3WOKaU",
    "y": "RcYpety4hVAR2mhyUSfU2J9-zzz6nsEfK-ro9b1oMws",
    "links": [ ... ]
}

Example GET a JWK set and the keys

This operation will retrieve both the set (which describes what the active kid is) and expand the keys.

The GET request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token?expand=keys

Note that, depending on how many old keys there are, the response may be large.

An example response to this request would be:

{
    "purpose": "wd_access_token",
    "allowedKeyUse": "enc",
    "activeKeyID": "e663e54e-4bcb-422d-9082-163355d70777",
    "keys": {
        "items": [
            {
                "kid": "e663e54e-4bcb-422d-9082-163355d70777",
                "kty": "EC",
                "use": "enc",
                "crv": "P-256",
                "x": "ny6tBcdL0F7uB7_VhsXkiqCMvlZsB0LspbztM3WOKaU",
                "y": "RcYpety4hVAR2mhyUSfU2J9-zzz6nsEfK-ro9b1oMws",
                "links": [ ... ]
            },
            ... ! POSSIBLY MANY MORE KEY ENTRIES !
        ],
        "links": [ ... ]
    },
    "links": [ ... ]
}

Example POST a JWK set generate active key

This operation will generate a new active key.

The POST request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token/generate-active-key

Note that this will disable the currently active key if there was one.

The basic structure expected for the POST request for this resource is as follows:

{}

An example response to this request would be:

{
    "kid": "ae21e7ee-747e-4200-be67-82ee99dbe7aa",
    "links": [ ... ]
}

Example PATCH a JWK set

This operation will switch back to a previously used key (assuming that it hasn't been deleted since it was de-activated).

The PATCH request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token

The structure expected for this PATCH request is as follows:

{
    "activeKeyID": "[the old key's kid value]"
}

Example PATCH active JWK set key

This operation will disable the active key, leaving the set for embedding interviews effectively disabled (that is, out of concern for a security breach).

The PATCH request URL looks like:

/opa-hub/api/12.2.39/jwksets/wd_access_token

The structure expected for this PATCH request is as follows:

{
    "activeKeyID": null
}