Request and Response

The Core API is the group of Authlete APIs that process OAuth 2.0 and OpenID Connect protocol requests, such as /auth/authorization, /auth/token, and /auth/userinfo. Your authorization server receives requests from client applications at its endpoints and delegates the protocol processing to these APIs. This page explains the request and response structure shared by the Core APIs.

Request Format

Core APIs accept an HTTP POST request with a JSON body. Authenticate with a Service Access Token in the Authorization header:

curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": "response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb%2Fexample.com" }'

Replace us.authlete.com with your cluster host (e.g. eu.authlete.com, jp.authlete.com) if you use a different region. See Authentication for how to obtain a Service Access Token.

Main Request Parameters

The exact set of request parameters differs per API and depends on which OAuth/OIDC specifications your service supports, so it cannot be fully generalized — always check the API Reference of the API you are calling. That said, the following parameters appear across many Core APIs:

Parameter	Description
`parameters`	The request your endpoint received from the client, passed as-is: the query string for the authorization endpoint, or the `application/x-www-form-urlencoded` request body for the token endpoint.
`clientId`	The client ID. When the client authenticates with `client_secret_basic`, extract it from the `Authorization: Basic` header of the request to your token endpoint.
`clientSecret`	The client secret, extracted from the `Authorization: Basic` header in the same way.
`clientCertificate`	The client certificate from the mutual TLS connection. Required when supporting mTLS client authentication or certificate-bound access tokens (RFC 8705).
`ticket`	The ticket returned by the first API of a two-step call (e.g. /auth/authorization), passed to the second API (e.g. /auth/authorization/issue). See Two-Step API Calls.
`token`	The access token to inspect, for APIs such as /auth/introspection and /auth/userinfo.
`subject`	The unique identifier of the end-user your server has authenticated, passed to issuing APIs such as /auth/authorization/issue.

Supporting additional specifications adds parameters accordingly — for example, DPoP (RFC 9449) adds dpop, htm, and htu to token and introspection requests.

Pass Client Request Parameters As-Is

Your authorization server is expected to pass the parameters it receives at its authorization endpoint and token endpoint to the corresponding Authlete APIs as-is — you usually MUST NOT modify or pre-process them. For example, if you want to check the values of the scope parameter in an authorization request, you don’t have to verify them before invoking the /auth/authorization API. Instead, include the whole query string as the value of the parameters field. Authlete verifies the request and returns the validated scope values in its response, which your authorization server can then use safely.

Implementing your own verification or modification before invoking /auth/authorization or /auth/token is risky. You might bypass Authlete’s protocol handling and error checking, and in the worst case your authorization server could become non-compliant with OAuth 2.0 / OpenID Connect.

Response Format

Core API responses share the following fields:

Field	Description
`resultCode`	A code identifying the processing result (e.g. `A004001`). Useful for logging and troubleshooting.
`resultMessage`	A human-readable description of the result.
`action`	The next step your server should take. This is the field your implementation must branch on.
`responseContent`	Content to use when building the response to the client, such as a JSON body or a redirect URI with error parameters.

The action field is the heart of the Core API programming model: it tells your authorization server what kind of HTTP response to return to the client, or which Authlete API to call next. See Action Handling for details.

Never branch your processing on resultCode. Result codes are diagnostic information; the contract for what to do next is expressed solely by action.

Introduction to Authlete

Quickstarts

Concepts

Developer Resources

Tools

Request Format

Main Request Parameters

Pass Client Request Parameters As-Is

Response Format

​Request Format

​Main Request Parameters

​Pass Client Request Parameters As-Is

​Response Format

Request Format

Main Request Parameters

Pass Client Request Parameters As-Is

Response Format