openapi: 3.0.3
info:
  title: Authlete Authorization Endpoint Pushed Authorization Endpoint API
  description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n"
  version: 3.0.16
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: 🇺🇸 US Cluster
  url: https://us.authlete.com
- description: 🇯🇵 Japan Cluster
  url: https://jp.authlete.com
- description: 🇪🇺 Europe Cluster
  url: https://eu.authlete.com
- description: 🇧🇷 Brazil Cluster
  url: https://br.authlete.com
security:
- bearer: []
tags:
- name: Pushed Authorization Endpoint
  description: API endpoints for implementing OAuth 2.0 Pushed Authorization Requests (PAR).
  x-tag-expanded: false
paths:
  /api/{serviceId}/pushed_auth_req:
    post:
      summary: Process Pushed Authorization Request
      description: 'This API creates a pushed request authorization. It authenticates the client and creates a authorization_uri to be returned by the authorization server.

        '
      parameters:
      - in: path
        name: serviceId
        description: A service ID.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pushed_authorization_request'
            example:
              parameters: response_type=code%20id_token&client_id=5921531358155430&redirect_uri=https%3A%2F%2Fserver.example.com%2Fcb&state=SOME_VALUE_ABLE_TO_PREVENT_CSRF&scope=openid&nonce=SOME_VALUE_ABLE_TO_PREVENT_REPLAY_ATTACK&code_challenge=5ZWDQJiryK3eaLtSeFV8y1XySMCWtyITxICLaTwvK8g&code_challenge_method=S256
              clientId: '5921531358155430'
              clientSecret: P_FouxWlI7zcOep_9vBwR9qMAVJQiCiUiK1HrAP4GziOyezHQpqY0f5dHXK4JT4tnvI51OkbWVoEM9GnOyJViA
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/pushed_authorization_request'
            example:
              parameters: response_type=code%20id_token&client_id=5921531358155430&redirect_uri=https%3A%2F%2Fserver.example.com%2Fcb&state=SOME_VALUE_ABLE_TO_PREVENT_CSRF&scope=openid&nonce=SOME_VALUE_ABLE_TO_PREVENT_REPLAY_ATTACK&code_challenge=5ZWDQJiryK3eaLtSeFV8y1XySMCWtyITxICLaTwvK8g&code_challenge_method=S256
              clientId: '5921531358155430'
              clientSecret: P_FouxWlI7zcOep_9vBwR9qMAVJQiCiUiK1HrAP4GziOyezHQpqY0f5dHXK4JT4tnvI51OkbWVoEM9GnOyJViA
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pushed_authorization_response'
              example:
                resultCode: A245001
                resultMessage: '[A245001] Successfully registered a request object for client (5921531358155430), URI is urn:ietf:params:oauth:request_uri:CAK9YEtNorwXE3UwSyihsBOL0jFrqUup7yAACw5y5Zg.'
                action: CREATED
                requestUri: urn:ietf:params:oauth:request_uri:CAK9YEtNorwXE3UwSyihsBOL0jFrqUup7yAACw5y5Zg
                responseContent: '{"expires_in":600,"request_uri":"urn:ietf:params:oauth:request_uri:CAK9YEtNorwXE3UwSyihsBOL0jFrqUup7yAACw5y5Zg"}'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: pushed_auth_req_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/pushed_auth_req \

          -H ''Content-Type: application/json'' \

          -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \

          -d ''{ "parameters": "response_type=code%20id_token&client_id=5921531358155430&redirect_uri=https%3A%2F%2Fserver.example.com%2Fcb&state=SOME_VALUE_ABLE_TO_PREVENT_CSRF&scope=openid&nonce=SOME_VALUE_ABLE_TO_PREVENT_REPLAY_ATTACK&code_challenge=5ZWDQJiryK3eaLtSeFV8y1XySMCWtyITxICLaTwvK8g&code_challenge_method=S256", "clientId": "5921531358155430", "clientSecret" : "P_FouxWlI7zcOep_9vBwR9qMAVJQiCiUiK1HrAP4GziOyezHQpqY0f5dHXK4JT4tnvI51OkbWVoEM9GnOyJViA"}''

          '
      - lang: java
        label: java
        source: 'AuthleteConfiguration conf = ...;

          AuthleteApi api = AuthleteApiFactory.create(conf);


          PushedAuthReqRequest req = new PushedAuthReqRequest();

          req.setParameters(...);

          req.setClientId("57297408867");

          req.setClientSecret("J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A");


          api.token(req);

          '
      - lang: python
        source: 'conf = ...

          api = AuthleteApiImpl(conf)


          req = PushedAuthReqRequest()

          req.parameters = ...

          req.clientId = ''57297408867''

          req.clientSecret = ''J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A''


          api.token(req)

          '
      tags:
      - Pushed Authorization Endpoint
components:
  responses:
    '401':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001202
            resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
    '400':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001201
            resultMessage: '[A001201] /auth/authorization, TLS must be used.'
    '500':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001101
            resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
    '403':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001215
            resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.'
  schemas:
    pushed_authorization_request:
      type: object
      required:
      - parameters
      properties:
        parameters:
          type: string
          description: 'The pushed authorization request body received from the client application.


            The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the request from

            the client application.

            '
        clientId:
          type: string
          description: 'The client ID extracted from `Authorization` header of the pushed request from the client application.

            '
        clientSecret:
          type: string
          description: 'The client secret extracted from `Authorization` header of the pushed authorization request from the client application.

            '
        clientCertificate:
          type: string
          description: The client certificate from the MTLS connection to pushed authorization endpoint from the client application.
        clientCertificatePath:
          type: array
          items:
            type: string
          description: 'The certificate path presented by the client during client authentication. These certificates are strings in PEM format.

            '
        dpop:
          type: string
          description: 'DPoP Header

            '
        htm:
          type: string
          description: 'HTTP Method (for DPoP validation).

            '
        htu:
          type: string
          description: 'HTTP URL base (for DPoP validation).

            '
        oauthClientAttestation:
          type: string
          description: 'The value of the `OAuth-Client-Attestation` HTTP header, which is defined in the specification

            of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).

            '
        oauthClientAttestationPop:
          type: string
          description: 'The value of the `OAuth-Client-Attestation-PoP` HTTP header, which is defined in the specification

            of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).

            '
        dpopNonceRequired:
          type: boolean
          description: 'The flag indicating whether to require the DPoP proof JWT to include the `nonce` claim. Even if

            the service''s `dpopNonceRequired` property is `false`, calling the `/pushed_auth_req` API with

            this `dpopNonceRequired` parameter `true` will force the Authlete API to check whether the DPoP

            proof JWT includes the expected `nonce` value.

            '
    result:
      type: object
      properties:
        resultCode:
          type: string
          description: The code which represents the result of the API call.
        resultMessage:
          type: string
          description: A short message which explains the result of the API call.
    pushed_authorization_response:
      type: object
      properties:
        resultCode:
          type: string
          description: The code which represents the result of the API call.
        resultMessage:
          type: string
          description: A short message which explains the result of the API call.
        action:
          type: string
          enum:
          - CREATED
          - BAD_REQUEST
          - UNAUTHORIZED
          - FORBIDDEN
          - PAYLOAD_TOO_LARGE
          - INTERNAL_SERVER_ERROR
          description: The next action that the authorization server implementation should take. Any other value other than "CREATED" should be handled as unsuccessful result.
        requestUri:
          type: string
          description: 'The request_uri created to the client to be used as request_uri on the authorize call.

            '
        responseContent:
          type: string
          description: 'The content that the authorization server implementation is to return to the client

            application.

            '
        clientAuthMethod:
          type: string
          description: 'The client authentication method that the client application declares that it uses at the token

            endpoint. This property corresponds to `token_endpoint_auth_method` in [OpenID Connect Dynamic

            Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).

            '
          enum:
          - NONE
          - CLIENT_SECRET_BASIC
          - CLIENT_SECRET_POST
          - CLIENT_SECRET_JWT
          - PRIVATE_KEY_JWT
          - TLS_CLIENT_AUTH
          - SELF_SIGNED_TLS_CLIENT_AUTH
          - ATTEST_JWT_CLIENT_AUTH
        dpopNonce:
          type: string
          description: 'Get the expected nonce value for DPoP proof JWT, which should be used

            as the value of the `DPoP-Nonce` HTTP header.

            '
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '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.

        '