---
title: "Inspect an OAuth token for your resource"
method: POST
path: "/products/identity/resource-introspection"
tags: ["identity"]
---

# Inspect an OAuth token for your resource

`POST /products/identity/resource-introspection`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/products/identity/resource-introspection`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/products/identity/resource-introspection/post.ts> (a function with typed inputs; its response is checked against the schema)

Core authentication selects the resource owner. The resource must be an exact canonical HTTPS URI under a verified domain of that account. Checks the signed access token, resource audience, mcp scope, client, SVID, live session version, expiry and connected-site block. Invalid tokens return active:false; dependency failures return an error, never an inactive verdict. Credential responses are not cached.

## Request body

- object
  - `token` string, required
  - `resource` string, uri, required

## Response `200`

The token verdict.

- object
  - `data` union, required
    - object
      - `active` unknown, required
    - object
      - `active` unknown, required
      - `iss` string, uri, required
      - `sub` string, required
      - `svid` string, required
      - `aud` string, uri, required
      - `client_id` string, required
      - `exp` integer, required
      - `iat` integer, required
      - `token_type` 'access', required
      - `scope` 'mcp', required
      - `session_id` string, required
      - `token_version` integer, required
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `400`: VALIDATION_ERROR — token and resource must be supplied.
- `401`: AUTHENTICATION_ERROR — missing or invalid credentials.
- `403`: FORBIDDEN — the caller may not act on this account.
- `500`: Token verification could not complete because a dependency or internal operation failed.

## Changes

- **2026-10-28** `a9a10e328ba5`: 16 info
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `401`
  - the response property `error/details` became required for the status `403`
  - the response property `error/details` became required for the status `500`
  - …12 more
- **2026-10-28** `56d7c265a77a`: 4 breaking
  - the response property `error/details` became nullable for the status `400`
  - the response property `error/details` became nullable for the status `401`
  - the response property `error/details` became nullable for the status `403`
  - the response property `error/details` became nullable for the status `500`
- **2026-10-26** `f84ee4518b07`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/identity/resource-introspection/post.md)

---

[API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)