# `Ltix.JWT.KeySet`
[🔗](https://github.com/DecoyLex/ltix/blob/main/lib/ltix/jwt/key_set.ex#L1)

Platform public keys for verifying ID Token signatures.

Platforms publish their public keys at a key set URL. Ltix gets the keys
it needs to verify a launch from a key set that your application starts.

## Setup

Add a key set to your application's supervision tree.

    # lib/my_app/application.ex
    children = [
      Ltix.JWT.KeySet
    ]

To run more than one, or to choose the name, pass `:name` and set the
name in your config.

    children = [
      {Ltix.JWT.KeySet, name: MyApp.LtiKeys}
    ]

    config :ltix, key_set: MyApp.LtiKeys

You can also choose the key set for one call.

    Ltix.handle_callback(params, state, key_set: MyApp.LtiKeys)

## Keys

A platform's keys are kept for the number of seconds in its
`cache-control: max-age`, or 5 minutes without one. A key the platform has
rotated in is available on the first launch signed with it.

## Fetch limit

Each key set URL is fetched at most once every 30 seconds, however many
launches arrive and whatever key IDs they have. Change the 30 seconds with
the `:refetch_interval` option of `start_link/1`. After a failed fetch,
launches for that platform return its error until the interval has passed.

A fetch retries a temporary failure up to three times. Pass `retry: false`
in `:req_options` to disable retries.

# `get_key`

```elixir
@spec get_key(Ltix.Registration.t(), String.t(), keyword()) ::
  {:ok, Ltix.JWK.t()} | {:error, Exception.t()}
```

Get the platform's public key with the key ID `kid`.

Returns `Ltix.Errors.Security.KidNotFound` when the platform has no key
with that ID.

## Options

  * `:key_set` - name of the key set to use (defaults to the application
    configuration, then `Ltix.JWT.KeySet`)
  * `:req_options` - `Req` options for requests to the key set URL
  * `:local_network_access` - `:local` or `:loopback` to fetch a key set
    from a private network address or this machine (defaults to
    application config, then `:none`)

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start a key set.

## Options

* `:name` (`t:atom/0`) - Name of the key set. The default value is `Ltix.JWT.KeySet`.

* `:refetch_interval` (`t:integer/0`) - Seconds between fetches of one key set URL. The default value is `30`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*