Guardian provides a singular interface for authentication in Elixir applications that is token based. Tokens should be:

• tamper proof
• include a payload (claims) JWT tokens (the default) fit this description. When using Guardian, you'll need an implementation module.

  defmodule MyApp.Guardian do
    use Guardian, otp_app: :my_app
    def subject_for_token(resource, _claims), do: {:ok, to_string(resource.id)}
    def resource_from_claims(claims) do
      find_me_a_resource(claims["sub"]) # {:ok, resource} or {:error, reason}
    end
  end

  This module is what you will use to interact with tokens in your application. When you use Guardian, the :otp_app option is required. Any other option provided will be merged with the configuration in the config files. The Guardian module contains some generated functions and some callbacks.

generated-functions

Generated functions

default_token_type

default_token_type()

Overridable. Provides the default token type for the token - "access" Token types allow a developer to mark a token as having a particular purpose. Different types of tokens can then be used specifically in your app. Types may include (but are not limited to):

• "access"
• "refresh" Access tokens should be short lived and are used to access resources on your API. Refresh tokens should be longer lived and whose only purpose is to exchange for a shorter lived access token. To specify the type of token, use the :token_type option in the encode_and_sign function. Token type is encoded into the token in the "typ" field. Return - a string.

peek-token

peek(token)

Inspect a tokens payload. Note that this function does no verification. Return - a map including the :claims key.

config-config-key-default-nil

config(), config(key, default \\ nil)

Without argument config will return the full configuration Keyword list. When given a key and optionally a default, config will fetch a resolved value contained in the key. See Guardian.Config.resolve_value/1

encode_and_sign-resource-claims-opts

encode_and_sign(resource, claims \\ %{}, opts \\ [])

Creates a signed token. Arguments:

• resource - The resource to represent in the token (i.e. the user)
• claims - Any custom claims that you want to use in your token
• opts - Options for the token module and callbacks For more information on options see the documentation for your token module.

  # Provide a token using the defaults including the default_token_type
  {:ok, token, full_claims} = MyApp.Guardian.encode_and_sign(user)
  # Provide a token including custom claims
  {:ok, token, full_claims} = MyApp.Guardian.encode_and_sign(user, %{some: "claim"})
  # Provide a token including custom claims and a different token type/ttl
  {:ok, token, full_claims} =
    MyApp.Guardian.encode_and_sign(user, %{some: "claim"}, token_type: "refresh", ttl: {4, :weeks})

  The encode_and_sign function calls a number of callbacks on your implementation module. See Guardian.encode_and_sign/4

decode_and_verify-token-claims_to_check-opts

decode_and_verify(token, claims_to_check \\ %{}, opts \\ [])

Decodes a token and verifies the claims are valid. Arguments:

• token - The token to decode
• claims_to_check - A map of the literal claims that should be matched. If any of the claims do not literally match verification fails.
• opts - The options to pass to the token module and callbacks Callbacks: decode_and_verify calls a number of callbacks on your implementation module, See Guardian.decode_and_verify/4

  # Decode and verify using the defaults
  {:ok, claims} = MyApp.Guardian.decode_and_verify(token)
  # Decode and verify with literal claims check.
  # If the claims in the token do not match those given verification will fail
  {:ok, claims} = MyApp.Guardian.decode_and_verify(token, %{match: "claim"})
  # Decode and verify with literal claims check and options.
  # Options are passed to your token module and callbacks
  {:ok, claims} = MyApp.Guardian.decode_and_verify(token, %{match: "claim"}, some: "secret")

revoke-token-opts

revoke(token, opts \\ [])

Revoke a token. Note: this is entirely dependent on your token module and implementation callbacks.

{:ok, claims} = MyApp.Guardian.revoke(token, some: "option")

refresh-token-opts

refresh(token, opts \ [])

Refreshes the time on a token. This is used to re-issue a token with essentially the same claims but with a different expiry. Tokens are verified before performing the refresh to ensure only valid tokens may be refreshed. Arguments:

• token - The old token to refresh
• opts - Options to pass to the Implementation Module and callbacks Options:
• :ttl - The new ttl. If not specified the default will be used.

  {:ok, {old_token, old_claims}, {new_token, new_claims}} =
    MyApp.Guardian.refresh(old_token, ttl: {1, :hour})

  See Guardian.refresh

exchange-old_token-from_type-to_type-options

exchange(old_token, from_type, to_type, options)

Exchanges one token for another of a different type. Especially useful to trade in a refresh token for an access one. Tokens are verified before performing the exchange to ensure that only valid tokens may be exchanged. Arguments:

• old_token - The existing token you wish to exchange.
• from_type - The type the old token must be. Can be given a list of types.
• to_type - The new type of token that you want back.
• options - The options to pass to the token module and callbacks. Options: Options may be used by your token module or callbacks.
• ttl - The ttl for the new token See Guardian.exchange

Note: Copied from Guardian Docs