PIpipeshub-ai
OAuth Provider

Introspect a token

Changed on

OAuth 2.0 Token Introspection Endpoint (RFC 7662).

Check if a token is active and retrieve its metadata.

Use Cases:

  • Resource servers validating tokens
  • Debugging token issues
  • Checking token scopes before processing requests

Response:

  • Active token: Returns active: true with token metadata
  • Invalid/expired/revoked token: Returns only active: false
post/oauth2/introspect

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/oauth2/introspect
  • Auth
    none required

Request body

tokenstring required

The token to introspect

token_type_hint'access_token' | 'refresh_token'

Hint about token type

client_idstring required

Client ID

client_secretstring

Client secret. Not checked by the validator, but client authentication cannot succeed without it: when it is missing the route answers {active: false} even for a live token, for public and confidential clients alike. A wrong secret is 401 invalid_client.

Response

Token introspection result. {active: false} alone when the token is unknown, expired, revoked, issued to another client, or when client_secret is missing (even for a live token). username is present only for a token that acts as a user.

activeboolean required

Whether the token is currently active

scopestring

Scopes granted to the token

client_idstring

Client ID the token was issued to

usernamestring

User identifier (if user-based token)

token_typestring

Token type

expinteger

Token expiration timestamp (Unix epoch)

iatinteger

Token issuance timestamp (Unix epoch)

nbfinteger

Token not-before timestamp (Unix epoch)

user_idstring

User ID

audstring

Audience (client ID)

issstring

Issuer URL

jtistring

Unique token identifier

Changes

  • dbb5e203b445Revision changes
    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/x-www-form-urlencoded)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/json)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/x-www-form-urlencoded)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/json)

    • warning

      added the new authorization_pending enum value to the response property for the response status

    • warning

      added the new expired_token enum value to the response property for the response status

    • warning

      added the new slow_down enum value to the response property for the response status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • a90ab79f26a1Revision changes
    • warning

      added the new invalid_target enum value to the response property for the response status