README.md

# Access Token

[![Build Status](https://travis-ci.org/fertapric/access_token.svg?branch=master)](https://travis-ci.org/fertapric/access_token)

Access token utility library based on JSON Web Token (JWT).

## Installation

Add Access Token to your project's dependencies in `mix.exs`:

```elixir
def deps do
  [{:access_token, "~> 1.0"}]
end
```

Fetch your project's dependencies:

```shell
$ mix deps.get
```

And configure the secret signing key in your application environment, usually defined
in `config/config.exs`:

```elixir
config :access_token, key: "6m/pr714TP8ijQeVdJ2gBOxuYwrD7nR/p5BhhcQ2ejURZpNYz9T//ze9mfx+TNpo"
```

## Usage

Access Token provides a simple interface to generate and process access tokens:

```elixir
iex> access_token = AccessToken.encode(%{user_id: 1})
iex> AccessToken.decode(access_token)
{:ok, %{user_id: user_id}}
```

See [`encode/2`](https://hexdocs.pm/access_token/AccessToken.html#encode/2) and [`decode/1`](https://hexdocs.pm/access_token/AccessToken.html#decode/1) for more information.

### Plug

`AccessToken.Plug` is a plug for extracting the access token from the request.

The token may be sent by the request either via the params with key `access_token` or a header with name `Authorization` and content `Bearer <access token>`.

To use it, just plug it into the desired module:

```elixir
plug AccessToken.Plug
```

If present, the access token will be accessible through the `assigns` map of the connection.

```elixir
conn.assigns[:access_token]
```

**Options**

  * `:param` - The name of the HTTP *request* parameter to check for
    the access token. Default value is `access_token`.

      ```elixir
      plug AccessToken.Plug, param: "token"
      ```

  * `:http_header` - The name of the HTTP *request* header to check for
    the access token. Default value is `authorization`.

      ```elixir
      plug AccessToken.Plug, http_header: "custom-authorization"
      ```

  * `:http_header_prefix` - The prefix of the HTTP *request* authorization header.
    Default value is `Bearer`.

      ```elixir
      plug AccessToken.Plug, http_header_prefix: "Token"
      ```

  * `:assign_to` - The name of the key to assign the access token.
    Defaults to `:access_token`

      ```elixir
      plug AccessToken.Plug, assign_to: :token
      ```

  * `:error_status` - The status code to be returned in case the access token is not
    present. The status can be `nil`, an integer or an atom. The list of allowed atoms
    is available in `Plug.Conn.Status`. Defaults to `:unauthorized`

      ```elixir
      plug AccessToken.Plug, error_status: :forbidden
      ```

  * `:error_handler` - The function to be called in case the access token is not
    present. The `:error_handler` is set using a `{module, function, args}` tuple.
    The function will receive the `conn` followed by the list of `args` provided.

      ```elixir
      plug AccessToken.Plug,
        error_handler: {Phoenix.Controller, :render, [MyAppWeb.ErrorView, "401.json"]}
      ```

## Documentation

Documentation is available at https://hexdocs.pm/access_token

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fertapric/access_token. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

### Running tests

Clone the repo and fetch its dependencies:

```shell
$ git clone https://github.com/fertapric/access_token.git
$ cd access_token
$ mix deps.get
$ mix test
```

### Building docs

```shell
$ mix docs
```

## Copyright and License

Copyright 2017 Fernando Tapia Rico

Access Token source code is licensed under the [MIT License](LICENSE).