JWT Keys

Fields

FieldValueReq/DefaultNotes
id id Auto-generated Key's ID. Always starts with "jky_". Example: jky_0vRHaJyOFdkV3QVJpUJqJQ
algo hs256,
rs256
Required Key's algorithm.
expired boolean Has this key been replaced? After a short time, key is deleted.
key string Optional The key; auto-generated if not provided.
use sign Required Key's use.

Permissions

MethodPermissions
List, Get, Create, Delete admin_realm

List keys

List all keys on the current realm.

Parameters

ParamValueDefault
after realm_id ID of the last realm you've seen
max_results integer 100 Range: 1-100
sort id id
direction asc,
desc
desc

Request

Example
GET /v1/jwt_keys
AuthRocket::JwtKey.all

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "jky_0vRHaJyOFdkV3QVJpUJqJQ",
      "algo" : "hs256",
      "expired" : false,
      "key" : "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
      "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "use" : "sign"
    }
  ]
}
[#<AuthRocket::JwtKey:0x3fde5d71d448>
  id: "jky_0vRHaJyOFdkV3QVJpUJqJQ",
  attribs: {
    "algo"=>"hs256",
    "expired"=>false,
    "key"=>"jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "use"=>"sign"
  },
  metadata: {
    "more_results"=>false
  }
]

Get a key

Retrieve a specific key.

Request

Example
GET /v1/jwt_keys/:key_id
AuthRocket::JwtKey.find 'jky_0vRHaJyOFdkV3QVJpUJqJQ'

Response

Example

Status: 200

{ "id" : "jky_0vRHaJyOFdkV3QVJpUJqJQ",
  "algo" : "hs256",
  "expired" : false,
  "key" : "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "use" : "sign"
}
#<AuthRocket::JwtKey:0x3fde5d71d448>
  id: "jky_0vRHaJyOFdkV3QVJpUJqJQ",
  attribs: {
    "algo"=>"hs256",
    "expired"=>false,
    "key"=>"jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "use"=>"sign"
  }

Create a key

Create a new key.

If key is unspecified, will automatically generate a key.

Request

Example
POST /v1/jwt_keys
{ "jwt_key" :
  { "algo" : "hs256",
    "use" : "sign"
  }
}
key = AuthRocket::JwtKey.create(
  algo: 'hs256',
  use: 'sign'
)

Response

Example

Status: 201, with same body as Get a Key.

On success, returns same object as Get a Key.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::JwtKey:0x3fde5d77e0f4> id: nil, ...
key.errors?
# => true
key.valid?
# => false
key.errors
# => ["Algo can't be blank"]

Events

Triggers a realm.updated event.

Delete a key

Deletes a key.

By default, marks the key as expired and immediately quits using it for new tokens, but will continue to use it to verify existing tokens for a few hours.

To delete it immediately, use force=true. This is useful if the key was compromised.

A replacement key will be automatically generated as soon as it’s needed, which in most cases will be very quickly. If you desire to create your own replacement key, it is recommended to create the new key first and then delete the old one.

Parameters

ParamValueDefault
force boolean false Delete immediately instead of in a few hours

Request

Example
DELETE /v1/jwt_keys/:key_id
DELETE /v1/jwt_keys/:key_id&force=true
key=AuthRocket::JwtKey.find 'jky_0vRHaJyOFdkV3QVJpUJqJQ'
key.delete
key.delete force: true

Response

Example

Status: 202

On success, returns original object.

On failure, returns false.

Events

Triggers a realm.updated event.

Questions? Find a Typo? Get in touch.