Using the JWK Sets REST API

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.27/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.27/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.27/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.27/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.27/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.27/jwksets/wd_access_token

The structure expected for this PATCH request is as follows:

{
    "activeKeyID": null
}