# Access Token
[](https://travis-ci.org/fertapric/access_token)
Access token utility library.
## Installation
Add Access Token to your project's dependencies in `mix.exs`:
```elixir
def deps do
[{:access_token, "~> 2.0"}]
end
```
And fetch your project's dependencies:
```shell
$ mix deps.get
```
## Usage
Access Token provides a simple interface to generate access tokens:
```elixir
iex> AccessToken.generate()
"MPjl2Y5AkvtP30rFb3ABRwkYNWsuRhJXkRQLhjaweqsC7H4fg8H2UmY5RpOkbO05"
iex> AccessToken.generate(20)
"XpT7OoqccDKg8Oa14B5w"
```
### 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 (`access_token` by default) or authorization headers (`Authorization: Bearer <access token>` by default).
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).
