> For the complete documentation index, see [llms.txt](https://docs.tpi.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tpi.dev/api-integration-guide/token-lifecycle-management-mechanism/token-introspection.md).

# Token Introspection

Verify the legitimacy of the access token or refresh token.

Example request:

```
curl -v -X POST https://{digiRunner_DOMAIN}/oauth/introspection \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'token={access_token}' \
-d 'token_type_hint=access_token' \
-d 'client_id={client_id}' \
-d 'client_secret={client_secret}'
```

Parameters with details:

<table><thead><tr><th width="201">Parameter</th><th width="87">Type</th><th width="130">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td>String</td><td>Required</td><td>Token to be introspected</td></tr><tr><td><code>token_type_hint</code></td><td>String</td><td>Required</td><td><p>Specifies which type of token to introspect:</p><p>To introspect an access token, use <code>access_token</code> as the value; to introspect a refresh token, use <code>refresh_token</code> as the value</p></td></tr><tr><td><code>client_id</code></td><td>String</td><td>Required</td><td>Client ID registered with digiRunner</td></tr><tr><td><code>client_secret</code></td><td>String</td><td>Optional</td><td><p><strong>Scenario I. Higher-Security (Client Password Required)</strong></p><p>Client Password registered with digiRunner</p><p></p><p><strong>Scenario II. PKCE + Public Client (Client Password Not Required)</strong></p><p>When the <strong>Public Client (With PKCE)</strong> option is selected in digiRunner's <strong>OAuth grant type</strong>, the parameter is not required.</p></td></tr></tbody></table>

### **Example of Successful Response**

Example:

```
{
"active": true,
"scope": "openid email profile 2000000086 2000000088",
"client_id": "tspldapclient",
"username": "Tsp Lee",
"token_type": "access_token",
"exp": 1685513177,
"iat": 1685426777,
"nbf": 1685426777,
"sub": "tspldapuser",
"aud": "YWRtaW5BUEk",
"iss": "https://10.20.30.88:18442/dgrv4/ssotoken/LDAP",
"jti": "882207db-4f84-433c-9508-1e1fb077ae13"
}
```

Parameters with details:

<table><thead><tr><th width="155">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>active</code></td><td>Boolean</td><td>Indicates whether the token was issued by digiRunner, hasn't been revoked by the resource owner, and is still within its valid period. Returns true or false.</td></tr><tr><td><code>scope</code></td><td>String</td><td>Specifies the range of resources that the access token is granted permission to access</td></tr><tr><td><code>client_id</code></td><td>String</td><td>Use <code>client_id</code> as the value for OAuth</td></tr><tr><td><code>username</code></td><td>String</td><td>Identifies the user who authorized this token, such as an alias on the application</td></tr><tr><td><code>token_type</code></td><td>String</td><td>Indicates the type of the token, such as <code>access_token</code> or <code>refresh_token</code></td></tr><tr><td><code>exp</code></td><td>Number</td><td>Token expiration time, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC</td></tr><tr><td><code>iat</code></td><td>Number</td><td>Token issuance time by the OAuth Server, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC when the token is issued by the OAuth Server.</td></tr><tr><td><code>nbf</code></td><td>Number</td><td>Token invalid time, an integer indicating the seconds since 1970-01-01T00:00:00Z UTC before the token becomes valid</td></tr><tr><td><code>sub</code></td><td>String</td><td>Identifies the user who authorized the token</td></tr><tr><td><code>aud</code></td><td>String</td><td>Indicates the audience intended to use the token</td></tr><tr><td><code>iss</code></td><td>String</td><td>Indicates the authorization server issuing the token</td></tr><tr><td><code>jti</code></td><td>String</td><td>Unique ID of this token, such as a UUID used when storing the token in a database to prevent replay attacks</td></tr></tbody></table>

### **Example of Error Response** <a href="#toc163842130" id="toc163842130"></a>

If the client password is incorrect, a 401 Unauthorized HTTP status code and JSON response will be returned.

Example:

```
{
"timestamp": "1685332598344",
"status": 401,
"error": "Unauthorized",
"message": "The client account or password is incorrect. clientId: tspldapclient",
"path": "/oauth/introspection"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tpi.dev/api-integration-guide/token-lifecycle-management-mechanism/token-introspection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.