# `OzMcp.Auth.Challenge`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/auth/challenge.ex#L1)

A refusal of a request. It becomes an HTTP status and a
`WWW-Authenticate` header value.

# `error`

```elixir
@type error() :: nil | :invalid_token | :invalid_request | :insufficient_scope
```

# `t`

```elixir
@type t() :: %OzMcp.Auth.Challenge{
  description: String.t() | nil,
  error: error(),
  scopes: [String.t()]
}
```

# `error_code`

```elixir
@spec error_code(t()) ::
  :http_unauthorized | :http_bad_authorization | :http_insufficient_scope
```

The key of the internal error table of the context for the challenge.

# `from`

```elixir
@spec from(t() | atom()) :: t()
```

Turn the shortcut atoms that the `authenticate/2` contract allows into
a challenge and check a challenge: an unknown error, a description
that is not a string or nil and scopes that are not a list of scope
tokens are defects of the verifier. Any such value raises
`ArgumentError` and the caller must answer a server error, never a
pass.

# `header`

```elixir
@spec header(t(), String.t() | nil, [String.t()]) :: String.t()
```

Build the `WWW-Authenticate` value of the challenge.

`metadata_url` is the Protected Resource Metadata URL of the server.
`default_scopes` are used when the challenge holds no scopes of its
own. The description is cut to 200 characters. Each
character that the header cannot hold becomes `?`.

# `insufficient_scope`

```elixir
@spec insufficient_scope([String.t()], String.t() | nil) :: t()
```

The token is valid but misses scopes. HTTP 403. Raises `ArgumentError`
when a scope does not match the RFC 6749 scope-token syntax, when the
scopes are not a list, or when the description is neither a string nor
nil.

# `invalid_request`

```elixir
@spec invalid_request(String.t() | nil) :: t()
```

The request is malformed. HTTP 400. Raises `ArgumentError` when the
description is neither a string nor nil.

# `invalid_token`

```elixir
@spec invalid_token(String.t() | nil) :: t()
```

The bearer token is not valid. HTTP 401. Raises `ArgumentError` when
the description is neither a string nor nil.

# `missing_token`

```elixir
@spec missing_token() :: t()
```

The request carries no usable bearer credential. HTTP 401 without an
error parameter (RFC 6750, section 3.1).

---

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