# `AshVault.Errors.InvalidMacaroon`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/errors.ex#L493)

Raised or returned when a macaroon does not verify, and the reason is the token itself.

`:reason` says which check failed, and is safe to log:

  * `:bad_signature` — the token did not verify. This is the **only** reason given for
    any failure before the signature has verified: malformed bytes, an unknown envelope
    version, a token for another macaroon, a scope with no key, a crypto-erased scope,
    or a forged, tampered, reordered, truncated or appended-without-signature chain. A
    forged token must not learn which tenants exist or were erased; the precise reason
    is on the `[:ash_vault, :macaroon, :rejected]` telemetry event instead
  * `:scope_mismatch` — a genuine token for a different tenant than the request's
  * `:unknown_key_version` — a genuine token whose keyring the provider can no longer
    find (an inconsistent key store)
  * `:unenforced_caveats` — the token carries `phase: :authorize` caveats and the
    verifying read requires the caller to assert they are enforced
  * `:unknown_caveat` — a caveat this macaroon does not declare
  * `:caveat_type` — a caveat value whose encoded type disagrees with the declaration
  * `:expired` — an `expires_at` caveat has passed
  * `{:caveat_failed, name}` — a declared caveat's check refused the request
  * `:not_found` — the signature is good but no record has the token's identity

It is deliberately distinct from `AshVault.Errors.MacaroonRevoked` (the token was good
and has been withdrawn) and from `AshVault.Errors.ProviderUnavailable` (nothing was
decided; retry). An outage is never reported as an invalid token.

The struct carries no token bytes, no identity and no signature: a macaroon is a bearer
credential, and Ash logs errors verbatim.

# `exception`

```elixir
@spec exception(opts :: Keyword.t()) :: %AshVault.Errors.InvalidMacaroon{
  __exception__: true,
  bread_crumbs: term(),
  class: term(),
  macaroon: term(),
  path: term(),
  reason: term(),
  resource: term(),
  splode: term(),
  stacktrace: term(),
  vars: term()
}
```

Create an `Elixir.AshVault.Errors.InvalidMacaroon` without raising it.

## Keys

- :resource
- :macaroon
- :reason

---

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