# Knock

Knock API access for applications written in Elixir.

## Documentation

See the [package documentation]( as well as [API documentation]( for usage examples.

## Installation

Add the package to your `mix.exs` file as follows:

def deps do
    {:knock, "~> 0.1.0"}

## Configuration

Start by defining an Elixir module for your Knock instance:

defmodule MyApp.Knock do
  use Knock, otp_app: :my_app

To use the library you must provide a secret API key, provided in the Knock dashboard.

You can set it as an environment variable:


Or you can specify it manually in your configuration:

config :my_app, MyApp.Knock,
  api_key: "sk_12345"

Or you can pass it through when creating a client instance:

knock_client = "sk_12345")

## Usage

### Identifying users

|> Knock.Users.identify("jhammond", %{
  "name" => "John Hammond",
  "email" => "",

### Retrieving users

|> Knock.Users.get_user("jhammond")

### Sending notifies

|> Knock.notify("dinosaurs-loose", %{
  # user id of who performed the action
  "actor" => "dnedry",
  # list of user ids for who should receive the notif
  "recipients" => ["jhammond", "agrant", "imalcolm", "esattler"],
  # data payload to send through
  "data" => %{
    "type" => "trex",
    "priority" => 1,

### Signing JWTs

You can use the excellent `joken` package to [sign JWTs easily](
You will need to generate an environment specific signing key, which you can find in the Knock dashboard.

If you're using a signing token you will need to pass this to your client to perform authentication.
You can read more about [clientside authentication here](

priv = System.get_env("KNOCK_SIGNING_KEY")
now = DateTime.utc_now()

claims = %{
  # The user id to sign this key for
  "sub" => user_id,
  # When the token was issued
  "iat" => DateTime.to_unix(now),
  # When the token expires (1 hour)
  "exp" => DateTime.add(now, 3600, :seconds) |> DateTime.to_unix()

signer = Joken.Signer.create("RS256", %{"pem" => priv})
{:ok, token, _} = Joken.generate_and_sign(%{}, claims, signer)