# `WardrikCore.Credentials`

Gives tools the tokens of the person a turn acts for. For your own API keys, see
`WardrikCore.Keys`.

    defmodule MyApp.Vault do
      @behaviour WardrikCore.Credentials

      @impl true
      def resolve(%{principal: nil}, _opts), do: {:error, "There's no one to act for."}

      def resolve(%{name: name, principal: %{id: id}}, _opts) do
        case MyApp.Tokens.get(id, name) do
          nil -> {:authorize, "https://app.example.com/connect/#{name}"}
          token -> {:ok, token}
        end
      end
    end

Give it to an agent as `credentials: {MyApp.Vault, opts}`. A tool fetches what it needs:

    with {:ok, token} <- WardrikCore.Credentials.fetch(context, "github") do
      GitHub.create_issue(token, title)
    end

  * `{:authorize, url}` parks the call on a `WardrikCore.Authorization`.
  * Call `refused/2` when a service rejects a token, then fetch again.
  * Tokens are never saved or emitted. Keep them out of private data and attributes.

See the [Credentials](credentials.html) guide.

# `refused`
*optional* 

```elixir
@callback refused(WardrikCore.Credentials.Request.t(), opts :: term()) :: :ok
```

Called when a service refused the credential the request names. Optional.

# `resolve`

```elixir
@callback resolve(WardrikCore.Credentials.Request.t(), opts :: term()) ::
  {:ok, secret :: term()} | {:authorize, url :: String.t()} | {:error, term()}
```

Returns the credential the request names: `{:ok, secret}`, `{:authorize, url}` for a sign-in
first, or `{:error, reason}`.

# `fetch`

```elixir
@spec fetch(WardrikCore.Context.t(), String.t()) ::
  {:ok, term()} | {:park, WardrikCore.Authorization.t()} | {:error, term()}
```

Fetches the credential `name` for whoever the turn acts for.

Returns `{:park, authorization}` if the person must sign in first, and `{:error, reason}` if the
agent has no credentials module.

# `refused`

```elixir
@spec refused(WardrikCore.Context.t(), String.t()) :: :ok
```

Tells the credentials module that a service refused the credential `name`.

---

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