Process OAuth 2.0 Introspection Request

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.introspection.standardProcess({
    serviceId: "<id>",
    standardIntrospectionRequest: {
      parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.introspection.standard_process(service_id: '<id>', standard_introspection_request: Models::Components::StandardIntrospectionRequest.new(
  parameters: 'token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token'
))

unless res.standard_introspection_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Introspection.StandardProcess(ctx, "<id>", components.StandardIntrospectionRequest{
        Parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.StandardIntrospectionResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/auth/introspection/standard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": "<string>",
  "withHiddenProperties": true,
  "rsUri": "<string>",
  "httpAcceptHeader": "<string>",
  "introspectionSignAlg": "<string>",
  "introspectionEncryptionAlg": "<string>",
  "introspectionEncryptionEnc": "<string>",
  "sharedKeyForSign": "<string>",
  "sharedKeyForEncryption": "<string>",
  "publicKeyForEncryption": "<string>"
}
'

{
  "resultCode": "A145001",
  "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
  "action": "OK",
  "responseContent": "{\\\"sub\\\":\\\"john\\\",\\\"scope\\\":\\\"history.read timeline.read\\\",\\\"iss\\\":\\\"https://my-service.example.com\\\",\\\"active\\\":true,\\\"token_type\\\":\\\"Bearer\\\",\\\"exp\\\":1640416873,\\\"client_id\\\":\\\"26478243745571\\\"}"
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

POST

api

{serviceId}

auth

introspection

standard

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.introspection.standardProcess({
    serviceId: "<id>",
    standardIntrospectionRequest: {
      parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.introspection.standard_process(service_id: '<id>', standard_introspection_request: Models::Components::StandardIntrospectionRequest.new(
  parameters: 'token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token'
))

unless res.standard_introspection_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Introspection.StandardProcess(ctx, "<id>", components.StandardIntrospectionRequest{
        Parameters: "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token",
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.StandardIntrospectionResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/auth/introspection/standard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": "<string>",
  "withHiddenProperties": true,
  "rsUri": "<string>",
  "httpAcceptHeader": "<string>",
  "introspectionSignAlg": "<string>",
  "introspectionEncryptionAlg": "<string>",
  "introspectionEncryptionEnc": "<string>",
  "sharedKeyForSign": "<string>",
  "sharedKeyForEncryption": "<string>",
  "publicKeyForEncryption": "<string>"
}
'

{
  "resultCode": "A145001",
  "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
  "action": "OK",
  "responseContent": "{\\\"sub\\\":\\\"john\\\",\\\"scope\\\":\\\"history.read timeline.read\\\",\\\"iss\\\":\\\"https://my-service.example.com\\\",\\\"active\\\":true,\\\"token_type\\\":\\\"Bearer\\\",\\\"exp\\\":1640416873,\\\"client_id\\\":\\\"26478243745571\\\"}"
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

Authorizations

Authorization

string

header

required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

serviceId

string

required

A service ID.

Body

parameters

string

required

Request parameters which comply with the introspection request defined in "2.1. Introspection Request" in RFC 7662.

The implementation of the introspection endpoint of your authorization server will receive an HTTP POST [RFC 7231] request with parameters in the application/x-www-form-urlencoded format. It is the entity body of the request that Authlete's /api/auth/introspection/standard API expects as the value of parameters.

withHiddenProperties

boolean

Flag indicating whether to include hidden properties in the output.

Authlete has a mechanism whereby to associate arbitrary key-value pairs with an access token. Each key-value pair has a hidden attribute. By default, key-value pairs whose hidden attribute is set to true are not embedded in the standard introspection output.

If the withHiddenProperties request parameter is given and its value is true, `/api/auth/introspection/standard API includes all the associated key-value pairs into the output regardless of the value of the hidden attribute.

rsUri

string

The URI of the resource server making the introspection request.

If the rsUri request parameter is given and the token has audience values, Authlete checks if the value of the rsUri request parameter is contained in the audience values. If not contained, Authlete generates an introspection response with the active property set to false.

The rsUri request parameter is required when the resource server requests a JWT introspection response, i.e., when the value of the httpAcceptHeader request parameter is set to "application/token-introspection+jwt".

httpAcceptHeader

string

The value of the HTTP Accept header in the introspection request.

If the value of the httpAcceptHeader request parameter is "application/token-introspection+jwt", Authlete generates a JWT introspection response. See "4. Requesting a JWT Response" of "RFC 9701: JWT Response for OAuth Token Introspection" for more details.

introspectionSignAlg

string

The JWS alg algorithm for signing the introspection response. This parameter corresponds to introspection_signed_response_alg defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

The default value is RS256.

introspectionEncryptionAlg

string

The JWE alg algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_alg defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

If the introspectionEncryptionAlg request parameter is specified, Authlete generates a JWT introspection response encrypted with the algorithm by this property and the algorithm specified by the introspectionEncryptionEnc request parameter.

introspectionEncryptionEnc

string

The JWE enc algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_enc defined in "6. Client Metadata" of "RFC 9701: JWT Response for OAuth Token Introspection".

The default value is A128CBC_HS256.

sharedKeyForSign

string

The shared key for signing the introspection response with a symmetric algorithm.

The sharedKeyForSign request parameter is required when the introspection response is requested to be signed with a symmetric algorithm.

sharedKeyForEncryption

string

The shared key for encrypting the introspection response with a symmetric algorithm.

The sharedKeyForEncryption request parameter is required when the introspection response is requested to be encrypted with a symmetric algorithm.

publicKeyForEncryption

string

The public key for signing the introspection response with an asymmetric algorithm.

The publicKeyForEncryption request parameter is required when the introspection response is requested to be encrypted with an asymmetric algorithm.

Response

Token introspection completed successfully

resultCode

string

The code which represents the result of the API call.

resultMessage

string

A short message which explains the result of the API call.

action

enum<string>

The next action that the authorization server implementation should take.

Available options:

INTERNAL_SERVER_ERROR,

BAD_REQUEST,

OK,

JWT

responseContent

string

The content that the authorization server implementation is to return to the client application.