# `Oidcc.TokenIntrospection`
[🔗](https://github.com/erlef/oidcc/blob/ee3434ddec86c14471af8f8a8f159971e654da3c
/lib/oidcc/token_introspection.ex#L4)

OAuth Token Introspection

See https://datatracker.ietf.org/doc/html/rfc7662

## Telemetry

* `[:oidcc, :introspect_token, :start]`
  * Description: Emitted at the start of introspecting the token
  * Measurements: `%{system_time: non_neg_integer(), monotonic_time: integer()}`
  * Metadata: `%{issuer: :uri_string.uri_string(), client_id: String.t()}`

* `[:oidcc, :introspect_token, :stop]`
  * Description: Emitted at the end of introspecting the token
  * Measurements: `%{duration: integer(), monotonic_time: integer()}`
  * Metadata: `%{issuer: :uri_string.uri_string(), client_id: String.t()}`

* `[:oidcc, :introspect_token, :exception]`
  * Description: Emitted at the end of introspecting the token
  * Measurements: `%{duration: integer(), monotonic_time: integer()}`
  * Metadata: `%{issuer: :uri_string.uri_string(), client_id: String.t()}`

# `t`
*since 3.0.0* 

```elixir
@type t() :: %Oidcc.TokenIntrospection{
  active: boolean(),
  aud: binary() | :undefined,
  client_id: binary(),
  exp: pos_integer() | :undefined,
  extra: %{required(binary()) => term()},
  iat: pos_integer() | :undefined,
  iss: binary() | :undefined,
  jti: binary() | :undefined,
  nbf: pos_integer() | :undefined,
  scope: :oidcc_scope.scopes(),
  sub: binary() | :undefined,
  token_type: binary() | :undefined,
  username: binary() | :undefined
}
```

For details on the fields see:
* https://datatracker.ietf.org/doc/html/rfc7662#section-2.2

# `introspect`
*since 3.0.0* 

```elixir
@spec introspect(
  token :: String.t() | Oidcc.Token.t(),
  client_context :: Oidcc.ClientContext.t(),
  opts :: :oidcc_token_introspection.opts()
) :: {:ok, t()} | {:error, :oidcc_token_introspection.error()}
```

Introspect the given access token

For a high level interface using `Oidcc.ProviderConfiguration.Worker`
see `Oidcc.introspect_token/5`.

## Examples

    iex> {:ok, pid} =
    ...>   Oidcc.ProviderConfiguration.Worker.start_link(%{
    ...>     issuer: "https://api.login.yahoo.com"
    ...>   })
    ...>
    ...> {:ok, client_context} =
    ...>   Oidcc.ClientContext.from_configuration_worker(
    ...>     pid,
    ...>     "client_id",
    ...>     "client_secret"
    ...>   )
    ...>
    ...> Oidcc.TokenIntrospection.introspect(
    ...>   "access_token",
    ...>   client_context
    ...> )
    ...> # => {:ok, %Oidcc.TokenIntrospection{}}

---

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