Document toolboxDocument toolbox

Introspect

URLhttps://<baseurl>/introspect
Request method

POST with parameters as application/x-www-form-urlencoded data

Client authenticationSee supported methods
Request parametersSee below
Response elementsSee below
ExampleSee below

Introspect is a standard endpoint used by Resource Servers to determine the particuar Authentication Context for a by-reference Access Token. A Resource Server needs such information to validate incomming tokens before granting access to Proteted Resources it hosts. Note in contrast that  self-contained Access Tokens can be validated by a Resource Server without calling the Introspection endpoint. Each of the particular types of by-reference tokens  supported by the OIDC Provider from BankID have corresponding support in the Introspect endpoint.

Request parameters

(tick) = According to standard. (error) = Feature restriction. 

ParameterSupportDescription
token(tick)String value of the by-reference token
token_hint(error)Not supported

Response parameters

JSON structure containing relevant attributes for the Access Token in question. The following attributes are supported

(tick) = According to standard. (error) = Feature restriction. (warning) = In progress / future support. (info) = Custom additions

ParameterSupportDescription
active
(tick)Indicator of whether or not the presented token is currently active 
scope(tick)Scopes associated with the access token in question 
client_id(tick)Identifier of the OIDC client that requested the token
username???TBD
token_type(tick)Type of token
exp(tick)Expiration time for the token
iat(tick)Issuing time for the token
nbf(error)  
sub(warning)Subject identifier of the end-user with which the token is associated
aud(error)  
iss(tick)Identifier for the issuer of the token
jti(error)  
nnin_altsub(info)(warning)Norwegian National Identity Number of the end-user with which the token is associated (corresponds to nnin_altsub in IDToken). Only available for eligible OAuth Resource Servers. Note: an eligible Resource Server may get access to nnin even of the OIDC Client that received the access token in question is not eligible.

Example

The following example shows a request / response pair for the Introspect endpoint. The example is generated from Postman (which is configured as a client at the OIDC Provider). The value for the access token in the request (token=4497db915b5b479191c81a7854a2fa8) is taken from the corresponding example for the Token endpoint. 

Request / Response
POST /oidc/oauth/introspect HTTP/1.1
cache-control: no-cache
Postman-Token: e439063e-a9e5-4474-a81d-912f25b8ff8a
Content-Type: application/x-www-form-urlencoded
Authorization: Basic UG9zdG1hbjoxMjM0
User-Agent: PostmanRuntime/3.0.11-hotfix.2
Accept: */*
Host: preprod.bankidapis.no
Content-Length: 37
Connection: close

token=4497db915b5b479191c81a7854a2fa8
 
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Server: Microsoft-IIS/8.5
X-Powered-By: ARR/3.0
X-Powered-By: ASP.NET
Date: Thu, 25 May 2017 11:20:30 GMT
Connection: close
Content-Length: 198

{
    "active": true,
    "client_id": "Postman",
    "exp": 1495714336,
    "iat": 1495710736,
    "iss": "https://preprod.bankidapis.no",
    "scope": "openid",
    "token_type": "Bearer",
    "username": "2b29ac70-800b-4eb5-bf3d-f0bd61a9e520"
}