OAuth2 token introspection (RFC 7662)

• Authorizationstring

  The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.

• tokenstringrequired
  Example"2YotnFZFEjr1zCsicMWpAA"

  1–8192 characters

• token_type_hintenum
  Possible values"access_token""refresh_token"
• client_idstring

  at most 256 characters · pattern ^[!-~]+$

• client_secretstring

  at most 512 characters

• client_assertion_typestring

  at most 128 characters

• client_assertionstring

  at most 16384 characters

No other properties are accepted.

• 200 OKapplication/jsonIntrospection response.+

  Introspection response.

  Headers

  • Cache-Controlno-store

  Body

  Token introspection response (RFC 7662 §2.2).

  • activebooleanrequired
    Exampletrue
  • scopestring
    Example"openid profile"
  • client_idstring
    Example"nauthera_2Rk9"
  • usernamestring
  • token_typestring

    How the token must be presented at a protected resource: DPoP when it is sender-constrained to a proof-of-possession key (RFC 9449 §5), Bearer otherwise. It always agrees with cnf — the two are derived from the same confirmation claim, so a response typed DPoP carries a cnf and one typed Bearer carries none.

    Example"Bearer"
  • cnfmap of strings

    Confirmation of the key the token is bound to, present only for a sender-constrained token and omitted entirely otherwise. jkt is the RFC 7638 SHA-256 thumbprint of the DPoP proof key (RFC 9449 §6.1).

    Example{"jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"}
  • expinteger
    Example1735689600
  • iatinteger
    Example1735686000
  • nbfinteger
  • substring
    Example"248289761001"
  • audstring
  • issstring · uri
    Example"https://auth.example.com"
  • jtistring
  • auth_timeinteger

    When the user signed in for the grant the token was issued from (RFC 9068 §2.2.1), the original sign-in's on a refreshed token. Absent for a token no user signed in for.

    Example1735685000
  • acrstring

    The authentication context class that sign-in satisfied (RFC 9068 §2.2.1). Absent when none was recorded.

  • amrarray of strings

    The authentication methods that sign-in used (RFC 8176). Absent when none were recorded.

    Example["pwd","otp"]
• 429 Too Many Requestsapplication/problem+jsonToo many requests.+

  Too many requests.

  Body

  RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.

  • titlestringrequired
    Example"Request validation failed"
  • statusintegerrequired
    Example400
  • typestring · uri
    Example"urn:problem-type:validation_error"
  • detailstring
    Example"One or more fields did not satisfy the API schema."
  • codeenum

    The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.

    Show moreShow less

    validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.

    Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.

    Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
  • instancestring
    Example"/introspect"
  • request_idstring
    Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
  • trace_idstring

    Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.

    Example"4bf92f3577b34da6a3ce929d0e0e4736"
  • errorsarray of objects

    Field-level violations (present for validation errors).

    Each item:

    A single field-level validation violation.

    +Show item attributesHide item attributes

    • fieldstringrequired

      Offending field, dotted for nested bodies (e.g. child.id).

      Example"token_type_hint"
    • codestringrequired

      Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.

      Example"not_allowed"
    • messagestringrequired
      Example"field token_type_hint must be one of [access_token, refresh_token]"
• Errorapplication/jsonOAuth2 error response (RFC 6749 §5.2).+

  OAuth2 error response (RFC 6749 §5.2).

  Headers

  • Cache-Controlno-store
  • WWW-Authenticatestring
  • DPoP-Noncestring

  Body

  An OAuth2 error response (RFC 6749 §5.2). iss (RFC 9207) is present on authorization-endpoint error responses so clients can detect mix-up.

  • errorstringrequired

    A single ASCII error code.

    Example"invalid_request"
  • error_descriptionstring
    Example"client_id, redirect_uri and response_type are required"
  • error_uristring · uri
  • statestring

    Echoed authorization-request state (RFC 6749 §4.1.2.1).

  • issstring · uri

    Issuer identifier on authorization error responses (RFC 9207).