# Introspect

Introspect is a [standard endpoint](https://tools.ietf.org/html/rfc7662) mainly used by Resource Servers to determine the
particular authorization context for an [Access Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md).

A Resource Server may need such information to validate incoming tokens before granting access to Protected Resources.

As the Access Tokens used by the OIDC Provider from BankID are self-contained, most of the validation process can be
performed without calling the Introspection endpoint, e.g. [token validation](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/verify-token.md).

If or when desired, you can use Introspection to check if the token has not been revoked for any reason prior
to the expiry time that is embedded in the token itself. That is unlikely to happen as the tokens are
short-lived and are not intended to be revoked.

> **Note**
>
> You will always find the up-to-date URL for the Introspection Endpoint in the [OpenID Configuration](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md) - as `introspection_endpoint`.

> **Warning**
>
> Note that the OIDC Provider from BankID does not support introspection of Refresh Tokens.

> **`token_type_hint` is required**
>
> BankID requires `token_type_hint=bid_access_token`, although [RFC 7662 section 2.1](https://tools.ietf.org/html/rfc7662#section-2.1) defines this parameter as optional.
>
> This requirement is not yet enforced. Once enforced, requests that omit `token_type_hint` or use a value other than `bid_access_token` return HTTP `200` with `{"active": false}`, even when the Access Token is valid. See [deprecations](https://docs.stoe.no/bankid-oidc-provider/resources/deprecations.md).
>
> Under [RFC 7662 section 2.2](https://tools.ietf.org/html/rfc7662#section-2.2), an authorized introspection request also returns `{"active": false}` when the caller cannot introspect that particular token. The response does not distinguish this case from an expired or revoked token.

## API

### Request

```http
POST [introspection_endpoint]
```

#### Parameters

The following [standard parameters](https://tools.ietf.org/html/rfc7662#section-2.1) are supported.

In addition comes parameters related to [Client authentication](https://docs.stoe.no/bankid-oidc-provider/core-concepts/client-authentication.md).

| Parameter       | Description                                                                                                                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token           | JWT value of the token subject to introspection                                                                                                                                                                                  |
| token_type_hint | **Must** contain the value `bid_access_token` to signify that the [Access Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md) in question is of the type supported by the OIDC Provider from BankID |

### Response

The response is a JSON structure containing the same claims as those contained in the JWT [Access Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md) subject to introspection.

The following additional claims are specific for the introspection response:

| Parameter   | Description                                                                                                                                                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active      | Indicator of whether or not the presented token is currently active                                                                                                                                                                                  |
| client_id   | Identifier of the OIDC client that requested the token                                                                                                                                                                                               |
| nnin_altsub | See [ID Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/id-token.md). This claim may be returned via introspection to eligible resources servers regardless of any such claim returned in the ID Token to the OIDC client in question |

> **Note**
>
> Note that the introspection response for tokens via the [Client Credential Grant](https://docs.stoe.no/bankid-oidc-provider/api/token.md) have a different structure since there is no end user involved in that case.

#### Example

```json
{
  "exp": 1629289953,
  "iat": 1629289653,
  "auth_time": 1629289634,
  "jti": "b47e41aa-f689-4f68-80d4-4fdda1855f8d",
  "iss": "https://auth.current.bankid.no/auth/realms/current",
  "aud": "tinfo",
  "sub": "2cd7cecd-d444-4685-bb04-8bbfdb45a069",
  "typ": "Bearer",
  "azp": "oidc-testclient",
  "nonce": "demoNonce",
  "session_state": "66801cef-7746-4dd6-a018-43bda5c7002b",
  "name": "Test User BankID",
  "given_name": "Test User",
  "family_name": "BankID",
  "birthdate": "2018-05-09",
  "acr": "urn:bankid:bid;LOA=4",
  "realm_access": {
    "roles": [
      "profile"
    ]
  },
  "resource_access": {
    "tinfo": {
      "roles": [
        "profile"
      ]
    }
  },
  "scope": "openid profile",
  "client_org_no": "918713867",
  "nnin_altsub": "09051888860",
  "amr": "BID",
  "resource_claims": {
  },
  "active": true,
  "bankid_altsub": "9578-6000-4-634582",
  "originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
  "partner_org_no": "918713867",
  "token_type": "Bearer",
  "client_name": "OIDC Testklient",
  "client_id": "oidc-testclient"
}
```