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.
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" }'
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. |
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. | 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. |
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.
