# `oidcc_token_introspection`
[🔗](https://github.com/erlef/oidcc/blob/ee3434ddec86c14471af8f8a8f159971e654da3c
/src/oidcc_token_introspection.erl#L4)

OAuth Token Introspection.

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

## Records

To use the records, import the definition:

```erlang
-include_lib(["oidcc/include/oidcc_token_introspection.hrl"]).
```

## Telemetry

See [`Oidcc.TokenIntrospection`](`m:'Elixir.Oidcc.TokenIntrospection'`).

# `error`
*since 3.0.0* 

```elixir
-type error() :: client_id_mismatch | introspection_not_supported | oidcc_http_util:error().
```

# `opts`
*since 3.0.0* 

```elixir
-type opts() ::
          #{preferred_auth_methods => [oidcc_auth_util:auth_method(), ...],
            request_opts => oidcc_http_util:request_opts(),
            dpop_nonce => binary(),
            client_self_only => boolean()}.
```

# `t`
*since 3.0.0* 

```elixir
-type t() ::
          #oidcc_token_introspection{active :: boolean(),
                                     client_id :: binary(),
                                     exp :: pos_integer(),
                                     scope :: oidcc_scope:scopes(),
                                     username :: binary(),
                                     iss :: binary(),
                                     token_type :: binary() | undefined,
                                     iat :: pos_integer() | undefined,
                                     nbf :: pos_integer() | undefined,
                                     sub :: binary() | undefined,
                                     aud :: binary() | undefined,
                                     jti :: binary() | undefined,
                                     extra :: #{binary() := term()}}.
```

Introspection Result.

See https://datatracker.ietf.org/doc/html/rfc7662#section-2.2.

# `introspect`
*since 3.0.0* 

```elixir
-spec introspect(Token, ClientContext, Opts) -> {ok, t()} | {error, error()}
                    when
                        Token :: oidcc_token:t() | binary(),
                        ClientContext :: oidcc_client_context:authenticated_t(),
                        Opts :: opts().
```

Introspect the given access token.

For a high level interface using `m:oidcc_provider_configuration_worker`
see `oidcc:introspect_token/5`.

## Examples

```erlang
{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

%% Get AccessToken

{ok, #oidcc_token_introspection{active = True}} =
  oidcc_token_introspection:introspect(AccessToken, ClientContext, #{}).
```

---

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