openapi: 3.0.3 info: title: Authlete API description: | Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the platform is configurable via API. This documentation will help you authenticate and integrate with Authlete to build powerful OAuth 2.0 and OpenID Connect servers. At a high level, the Authlete API is grouped into two categories: - **Management APIs**: Enable you to manage services and clients. - **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers. ## 🌐 API Servers Authlete is a global service with clusters available in multiple regions across the world: - πŸ‡ΊπŸ‡Έ **US**: `https://us.authlete.com` - πŸ‡―πŸ‡΅ **Japan**: `https://jp.authlete.com` - πŸ‡ͺπŸ‡Ί **Europe**: `https://eu.authlete.com` - πŸ‡§πŸ‡· **Brazil**: `https://br.authlete.com` Our customers can host their data in the region that best meets their requirements. ## πŸ”‘ Authentication All API endpoints are secured using **Bearer token authentication**. You must include an access token in every request: ``` Authorization: Bearer YOUR_ACCESS_TOKEN ``` ### Getting Your Access Token Authlete supports two types of access tokens: **Service Access Token** - Scoped to a single service (authorization server instance) 1. Log in to [Authlete Console](https://console.authlete.com) 2. Navigate to your service β†’ **Settings** β†’ **Access Tokens** 3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`) 4. Copy the generated token **Organization Token** - Scoped to your entire organization 1. Log in to [Authlete Console](https://console.authlete.com) 2. Navigate to **Organization Settings** β†’ **Access Tokens** 3. Click **Create Token** and select org-level permissions 4. Copy the generated token > ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only > access their specific service, while organization tokens can access all services within your org. ### Token Security Best Practices - **Never commit tokens to version control** - Store in environment variables or secure secret managers - **Rotate regularly** - Generate new tokens periodically and revoke old ones - **Scope appropriately** - Request only the permissions your application needs - **Revoke unused tokens** - Delete tokens you're no longer using from the console ### Quick Test Verify your token works with a simple API call: ```bash curl -X GET https://us.authlete.com/api/service/get/list \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ## πŸŽ“ Tutorials If you're new to Authlete or want to see sample implementations, these resources will help you get started: - [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/) - [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/) ## πŸ›  Contact Us If you have any questions or need assistance, our team is here to help: - [Contact Page](https://www.authlete.com/contact/) 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: Service Management description: API endpoints for managing services, including creation, update, and deletion of services. x-tag-expanded: false - name: Client Management description: API endpoints for managing OAuth clients, including creation, update, and deletion of clients. x-tag-expanded: false - name: Authorization Endpoint description: API endpoints for implementing OAuth 2.0 Authorization Endpoint. x-tag-expanded: false - name: Pushed Authorization Endpoint description: API endpoints for implementing OAuth 2.0 Pushed Authorization Requests (PAR). x-tag-expanded: false - name: Token Endpoint description: API endpoints for implementing OAuth 2.0 Token Endpoint. x-tag-expanded: false - name: Token Operations description: API endpoints for various token related operations, including creating, revoking and deleting access_tokens with specified scopes. x-tag-expanded: false - name: Introspection Endpoint description: API endpoints for implementing OAuth 2.0 Introspection Endpoint. x-tag-expanded: false - name: Revocation Endpoint description: API endpoint for implementing OAuth 2.0 Revocation Endpoint. x-tag-expanded: false - name: UserInfo Endpoint description: API endpoints for implementing OpenID Connect UserInfo Endpoint. x-tag-expanded: false - name: JWK Set Endpoint description: API endpoints for to generate JSON Web Key Set (JWKS) for a service. x-tag-expanded: false - name: Discovery Endpoint description: API endpoints for implementing OpenID Connect Discovery. x-tag-expanded: false - name: Configuration Endpoint description: API endpoint for accessing configuration settings for a service. x-tag-expanded: false - name: Dynamic Client Registration description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration. x-tag-expanded: false - name: CIBA description: API endpoints for implementing Client-Initiated Backchannel Authentication (CIBA). x-tag-expanded: false - name: Grant Management Endpoint description: API endpoint for implementing OAuth 2.0 grants, including grant management actions like updating and revoking grants. x-tag-expanded: false - name: Jose Object description: API endpoints for JOSE objects. x-tag-expanded: false - name: Device Flow description: API endpoints for implementing OAuth 2.0 Device Flow x-tag-expanded: false - name: Federation Endpoint description: API endpoints for implementing OpenID Federation using Authlete. x-tag-expanded: false - name: Verifiable Credential Issuer description: API endpoints for implementing and running a Verifiable Credential Issuer (VCI). x-tag-expanded: false - name: Hardware Security Key description: API endpoints for managing hardware security keys (HSK). x-tag-expanded: false - name: Utility Endpoints description: API endpoints for various utility operations. x-tag-expanded: false - name: Native SSO description: API endpoints for Native SSO x-tag-expanded: false paths: /api/{serviceId}/service/get: get: summary: Get Service description: | Get a service. If the access token can only view or modify clients underneath this service, but does not have access to view this service directly, a limited view of the service will be returned. parameters: - in: path name: serviceId description: A service ID. schema: type: string required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/service' examples: full: summary: Example showing the full service object. value: accessTokenDuration: 3600 accessTokenType: Bearer allowableClockSkew: 0 apiKey: 21653835348762 attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authorizationEndpoint: https://my-service.example.com/authz authorizationResponseDuration: 0 authorizationCodeDuration: 0 backchannelAuthReqIdDuration: 0 backchannelBindingMessageRequiredInFapi: false backchannelPollingInterval: 0 backchannelUserCodeParameterSupported: false claimShortcutRestrictive: false clientIdAliasEnabled: true clientsPerDeveloper: 0 createdAt: 1639373421000 dcrScopeUsedAsRequestable: false deviceFlowCodeDuration: 0 deviceFlowPollingInterval: 0 directAuthorizationEndpointEnabled: false directIntrospectionEndpointEnabled: false directJwksEndpointEnabled: false directRevocationEndpointEnabled: false directTokenEndpointEnabled: false directUserInfoEndpointEnabled: false dynamicRegistrationSupported: false errorDescriptionOmitted: false errorUriOmitted: false frontChannelRequestObjectEncryptionRequired: false grantManagementActionRequired: false hsmEnabled: false idTokenDuration: 0 introspectionEndpoint: https://my-service.example.com/introspection issSuppressed: false issuer: https://my-service.example.com metadata: - key: clientCount value: '1' missingClientIdAllowed: false modifiedAt: 1639373421000 mutualTlsValidatePkiCertChain: false nbfOptional: false number: 5041 parRequired: false pkceRequired: true pkceS256Required: false pushedAuthReqDuration: 0 refreshTokenDuration: 3600 refreshTokenDurationKept: false refreshTokenDurationReset: false refreshTokenKept: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false revocationEndpoint: https://my-service.example.com/revocation scopeRequired: false serviceName: My service serviceOwnerNumber: 2 singleAccessTokenPerSubject: false supportedClaimTypes: - NORMAL supportedDisplays: - PAGE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC supportedResponseTypes: - CODE supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC supportedScopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read supportedTokenAuthMethods: - CLIENT_SECRET_BASIC tlsClientCertificateBoundAccessTokens: false tokenEndpoint: https://my-service.example.com/token tokenExpirationLinked: false traditionalRequestObjectProcessingApplied: false unauthorizedOnClientConfigSupported: false userCodeLength: 0 limited: summary: Example showing the limited service object. value: apiKey: 21653835348762 description: This Service. number: 5041 serviceName: My service links: service_get_list: $ref: '#/components/links/service_get_list' service_update: $ref: '#/components/links/service_update' service_delete: $ref: '#/components/links/service_delete' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_get_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/service/get \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long serviceId = ...; api.getService(serviceId); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) serviceId = ... api.getService(serviceId) tags: - Service Management /api/service/get/list: get: summary: List Services description: | Get a list of services. If the access token can only view or modify clients underneath a service, but does not have access to view that service directly, a limited view of the service will be returned. Otherwise, all properties of the service are returned. If the access token is an administrative token, this returns a list of all services on the Authlete instance. Otherwise, all services that the access token can view, even in a limited fashion, are returned. parameters: - in: query name: start schema: type: integer format: int32 required: false description: Start index (inclusive) of the result set. The default value is 0. Must not be a negative number. - in: query name: end schema: type: integer format: int32 required: false description: End index (exclusive) of the result set. The default value is 5. Must not be a negative number. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/service_get_list_response' examples: full: summary: Example showing the full service view. value: start: 0 end: 5 totalCount: 1 services: - accessTokenDuration: 3600 accessTokenType: Bearer allowableClockSkew: 0 apiKey: 21653835348762 apiSecret: uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authorizationEndpoint: https://as.example.com/authz authorizationResponseDuration: 0 authorizationCodeDuration: 0 backchannelAuthReqIdDuration: 0 backchannelBindingMessageRequiredInFapi: false backchannelPollingInterval: 0 backchannelUserCodeParameterSupported: false claimShortcutRestrictive: false clientIdAliasEnabled: true createdAt: 1639373421000 dcrScopeUsedAsRequestable: false deviceFlowCodeDuration: 0 deviceFlowPollingInterval: 0 directAuthorizationEndpointEnabled: false directIntrospectionEndpointEnabled: false directJwksEndpointEnabled: false directRevocationEndpointEnabled: false directTokenEndpointEnabled: false directUserInfoEndpointEnabled: false dynamicRegistrationSupported: false errorDescriptionOmitted: false errorUriOmitted: false frontChannelRequestObjectEncryptionRequired: false grantManagementActionRequired: false hsmEnabled: false idTokenDuration: 0 introspectionEndpoint: https://my-service.example.com/introspection issSuppressed: false issuer: https://my-service.example.com metadata: - key: clientCount value: '1' missingClientIdAllowed: false modifiedAt: 1639373421000 mutualTlsValidatePkiCertChain: false nbfOptional: false number: 5041 parRequired: false pkceRequired: true pkceS256Required: false pushedAuthReqDuration: 0 refreshTokenDuration: 3600 refreshTokenDurationKept: false refreshTokenDurationReset: false refreshTokenKept: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false revocationEndpoint: https://my-service.example.com/revocation scopeRequired: false serviceName: My service serviceOwnerNumber: 2 singleAccessTokenPerSubject: false supportedClaimTypes: - NORMAL supportedDisplays: - PAGE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC supportedResponseTypes: - CODE supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC supportedScopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read supportedTokenAuthMethods: - CLIENT_SECRET_BASIC tlsClientCertificateBoundAccessTokens: false tokenEndpoint: https://my-service.example.com/token tokenExpirationLinked: false traditionalRequestObjectProcessingApplied: false unauthorizedOnClientConfigSupported: false userCodeLength: 0 limited: summary: Example showing the limited service view. value: start: 0 end: 5 totalCount: 1 services: - apiKey: 21653835348762 clientIdAliasEnabled: true number: 5041 serviceName: My service links: service_create: $ref: '#/components/links/service_create' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_get_list_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/9503564192/service/get/list?start=0\&end=5 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); int start = 0; int end = 5; api.getServiceList(start, end); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) start = 0 end = 5 api.getServiceList(start, end) tags: - Service Management /api/service/create: post: summary: Create Service description: | Create a new service. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/service' example: serviceName: My service issuer: https://my-service.example.com clientIdAliasEnabled: true supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedResponseTypes: - CODE authorizationEndpoint: https://my-service.example.com/authz pkceRequired: true tokenEndpoint: https://my-service.example.com/token supportedTokenAuthMethods: - CLIENT_SECRET_BASIC revocationEndpoint: https://my-service.example.com/revocation supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC introspectionEndpoint: https://my-service.example.com/introspection supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC accessTokenType: Bearer accessTokenDuration: 3600 refreshTokenDuration: 3600 supportedScopes: - name: timeline.read defaultEntry: false description: A permission to read your timeline. - name: history.read defaultEntry: false description: A permission to read your history. attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/service' responses: '200': description: Service created successfully (legacy compatibility) content: application/json: schema: $ref: '#/components/schemas/service' example: accessTokenDuration: 3600 '201': description: Service created successfully content: application/json: schema: $ref: '#/components/schemas/service' example: accessTokenDuration: 3600 accessTokenType: Bearer allowableClockSkew: 0 apiKey: 21653835348762 apiSecret: uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authorizationEndpoint: https://my-service.example.com/authz authorizationResponseDuration: 0 authorizationCodeDuration: 0 backchannelAuthReqIdDuration: 0 backchannelBindingMessageRequiredInFapi: false backchannelPollingInterval: 0 backchannelUserCodeParameterSupported: false claimShortcutRestrictive: false clientIdAliasEnabled: true clientsPerDeveloper: 0 createdAt: 1639373421000 dcrScopeUsedAsRequestable: false deviceFlowCodeDuration: 0 deviceFlowPollingInterval: 0 directAuthorizationEndpointEnabled: false directIntrospectionEndpointEnabled: false directJwksEndpointEnabled: false directRevocationEndpointEnabled: false directTokenEndpointEnabled: false directUserInfoEndpointEnabled: false dynamicRegistrationSupported: false errorDescriptionOmitted: false errorUriOmitted: false frontChannelRequestObjectEncryptionRequired: false grantManagementActionRequired: false hsmEnabled: false idTokenDuration: 0 introspectionEndpoint: https://my-service.example.com/introspection issSuppressed: false issuer: https://my-service.example.com metadata: - key: clientCount value: '0' missingClientIdAllowed: false modifiedAt: 1639373421000 mutualTlsValidatePkiCertChain: false nbfOptional: false number: 5041 parRequired: false pkceRequired: true pkceS256Required: false pushedAuthReqDuration: 0 refreshTokenDuration: 3600 refreshTokenDurationKept: false refreshTokenDurationReset: false refreshTokenKept: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false revocationEndpoint: https://my-service.example.com/revocation scopeRequired: false serviceName: My service serviceOwnerNumber: 2 singleAccessTokenPerSubject: false supportedClaimTypes: - NORMAL supportedDisplays: - PAGE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC supportedResponseTypes: - CODE supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC supportedScopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read supportedTokenAuthMethods: - CLIENT_SECRET_BASIC tlsClientCertificateBoundAccessTokens: false tokenEndpoint: https://my-service.example.com/token tokenExpirationLinked: false traditionalRequestObjectProcessingApplied: false unauthorizedOnClientConfigSupported: false userCodeLength: 0 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_create_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/service/create \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "serviceName": "My Service", ... }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); Service service = new Service(); service.setServiceName("My Service"); ... api.createService(service); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) service = Service() service.serviceName = 'My Service' ... api.createService(service) tags: - Service Management /api/{serviceId}/service/update: post: summary: Update Service description: | Update a service. parameters: - in: path name: serviceId description: A service ID. schema: type: string required: true requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/service' example: accessTokenDuration: 3600 accessTokenType: Bearer allowableClockSkew: 0 attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authorizationEndpoint: https://my-service.example.com/authz authorizationResponseDuration: 0 authorizationCodeDuration: 0 backchannelAuthReqIdDuration: 0 backchannelBindingMessageRequiredInFapi: false backchannelPollingInterval: 0 backchannelUserCodeParameterSupported: false claimShortcutRestrictive: false clientIdAliasEnabled: true clientsPerDeveloper: 0 dcrScopeUsedAsRequestable: false deviceFlowCodeDuration: 0 deviceFlowPollingInterval: 0 directAuthorizationEndpointEnabled: false directIntrospectionEndpointEnabled: false directJwksEndpointEnabled: false directRevocationEndpointEnabled: false directTokenEndpointEnabled: false directUserInfoEndpointEnabled: false dynamicRegistrationSupported: false errorDescriptionOmitted: false errorUriOmitted: false frontChannelRequestObjectEncryptionRequired: false grantManagementActionRequired: false hsmEnabled: false idTokenDuration: 0 introspectionEndpoint: https://my-service.example.com/introspection issSuppressed: false issuer: https://my-service.example.com missingClientIdAllowed: false mutualTlsValidatePkiCertChain: false nbfOptional: false parRequired: false pkceRequired: true pkceS256Required: false pushedAuthReqDuration: 0 refreshTokenDuration: 3600 refreshTokenDurationKept: false refreshTokenDurationReset: false refreshTokenKept: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false revocationEndpoint: https://my-service.example.com/revocation scopeRequired: false serviceName: My updated service singleAccessTokenPerSubject: false supportedClaimTypes: - NORMAL supportedDisplays: - PAGE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC supportedResponseTypes: - CODE supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC supportedScopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read supportedTokenAuthMethods: - CLIENT_SECRET_BASIC tlsClientCertificateBoundAccessTokens: false tokenEndpoint: https://my-service.example.com/token tokenExpirationLinked: false traditionalRequestObjectProcessingApplied: false unauthorizedOnClientConfigSupported: false userCodeLength: 0 application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/service' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/service' example: accessTokenDuration: 3600 accessTokenType: Bearer allowableClockSkew: 0 apiKey: 21653835348762 apiSecret: uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authorizationEndpoint: https://my-service.example.com/authz authorizationResponseDuration: 0 authorizationCodeDuration: 0 backchannelAuthReqIdDuration: 0 backchannelBindingMessageRequiredInFapi: false backchannelPollingInterval: 0 backchannelUserCodeParameterSupported: false claimShortcutRestrictive: false clientIdAliasEnabled: true clientsPerDeveloper: 0 createdAt: 1639373421000 dcrScopeUsedAsRequestable: false deviceFlowCodeDuration: 0 deviceFlowPollingInterval: 0 directAuthorizationEndpointEnabled: false directIntrospectionEndpointEnabled: false directJwksEndpointEnabled: false directRevocationEndpointEnabled: false directTokenEndpointEnabled: false directUserInfoEndpointEnabled: false dynamicRegistrationSupported: false errorDescriptionOmitted: false errorUriOmitted: false frontChannelRequestObjectEncryptionRequired: false grantManagementActionRequired: false hsmEnabled: false idTokenDuration: 0 introspectionEndpoint: https://my-service.example.com/introspection issSuppressed: false issuer: https://my-service.example.com metadata: - key: clientCount value: '1' missingClientIdAllowed: false modifiedAt: 1639373420725 mutualTlsValidatePkiCertChain: false nbfOptional: false number: 5041 parRequired: false pkceRequired: true pkceS256Required: false pushedAuthReqDuration: 0 refreshTokenDuration: 3600 refreshTokenDurationKept: false refreshTokenDurationReset: false refreshTokenKept: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false revocationEndpoint: https://my-service.example.com/revocation scopeRequired: false serviceName: My updated service serviceOwnerNumber: 2 singleAccessTokenPerSubject: false supportedClaimTypes: - NORMAL supportedDisplays: - PAGE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN supportedIntrospectionAuthMethods: - CLIENT_SECRET_BASIC supportedResponseTypes: - CODE supportedRevocationAuthMethods: - CLIENT_SECRET_BASIC supportedScopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read supportedTokenAuthMethods: - CLIENT_SECRET_BASIC tlsClientCertificateBoundAccessTokens: false tokenEndpoint: https://my-service.example.com/token tokenExpirationLinked: false traditionalRequestObjectProcessingApplied: false unauthorizedOnClientConfigSupported: false userCodeLength: 0 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_update_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/service/update \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "serviceName": "My updated service", ... }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); // Get an existing service. long serviceId = ...; Service service = api.getService(serviceId); // Update "service name". service.setAServiceName("My updated service"); api.updateService(service); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) # Get an existing service. serviceId = ... service = api.getService(serviceId) # Update "service name". service.serviceName = 'My updated service' api.updateService(service) tags: - Service Management /api/{serviceId}/service/delete: delete: summary: Delete Service ⚑ description: | Delete a service. parameters: - in: path name: serviceId description: A service ID. schema: type: string required: true responses: '204': description: The service was successfully deleted. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_delete_api x-code-samples: - lang: shell label: curl source: | curl -v -X DELETE https://us.authlete.com/api/9503564192/service/delete/21653835348762 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long serviceId = ...; api.deleteService(serviceId); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) serviceId = ... api.deleteService(serviceId) tags: - Service Management /api/{serviceId}/client/get/{clientId}: get: summary: Get Client description: | Get a client. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: A client ID. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client' example: applicationType: WEB attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authTimeRequired: false bcUserCodeRequired: false clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My client clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ clientType: CONFIDENTIAL createdAt: 1639468356000 defaultMaxAge: 0 derivedSectorIdentifier: my-client.example.com developer: john dynamicallyRegistered: false frontChannelRequestObjectEncryptionRequired: false grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN idTokenSignAlg: RS256 modifiedAt: 1639468356000 number: 6164 parRequired: false redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false responseTypes: - CODE - TOKEN serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_get_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/client/get/26478243745571 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = ...; api.getClient(clientId); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = ... api.getClient(clientId) tags: - Client Management /api/{serviceId}/client/get/list: get: summary: List Clients description: | Get a list of clients on a service. If the access token can view a full service (including an admin), all clients within the service are returned. Otherwise, only clients that the access token can view within the service are returned. - ViewClient: [] parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: query name: developer schema: type: string required: false description: | The developer of client applications. The default value is null. If this parameter is not set to `null`, client application of the specified developer are returned. Otherwise, all client applications that belong to the service are returned. - in: query name: start schema: type: integer format: int32 required: false description: Start index (inclusive) of the result set. The default value is 0. Must not be a negative number. - in: query name: end schema: type: integer format: int32 required: false description: End index (exclusive) of the result set. The default value is 5. Must not be a negative number. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_get_list_response' examples: full: summary: Example showing full client view. value: clients: - applicationType: WEB attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authTimeRequired: false bcUserCodeRequired: false clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My client clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ clientType: CONFIDENTIAL createdAt: 1639468356000 defaultMaxAge: 0 derivedSectorIdentifier: my-client.example.com dynamicallyRegistered: false frontChannelRequestObjectEncryptionRequired: false grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN idTokenSignAlg: RS256 modifiedAt: 1639468356000 number: 6164 parRequired: false redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false responseTypes: - CODE - TOKEN serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC end: 3 start: 0 totalCount: 1 limited: summary: Example showing limited client view. value: clients: - clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My client clientType: CONFIDENTIAL number: 6164 end: 3 start: 0 totalCount: 1 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_get_list_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/client/get/list?developer=john\&start=0\&end=5 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); String developer = "john"; int start = 0; int end = 5; api.getClientList(developer, start, end); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) developer = 'john' start = 0 end = 5 api.getClientList(developer, start, end) tags: - Client Management /api/{serviceId}/client/create: post: summary: Create Client description: | Create a new client. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/client' example: developer: john clientName: My Client clientIdAlias: my-client clientIdAliasEnabled: true clientType: CONFIDENTIAL applicationType: WEB grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN responseTypes: - CODE - TOKEN redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 tokenAuthMethod: CLIENT_SECRET_BASIC attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value responses: '200': description: Client created successfully (legacy compatibility) content: application/json: schema: $ref: '#/components/schemas/client' example: applicationType: WEB clientId: 26478243745571 '201': description: Client created successfully content: application/json: schema: $ref: '#/components/schemas/client' example: applicationType: WEB attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authTimeRequired: false bcUserCodeRequired: false clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My client clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ clientType: CONFIDENTIAL createdAt: 1639468356000 defaultMaxAge: 0 derivedSectorIdentifier: my-client.example.com developer: john dynamicallyRegistered: false frontChannelRequestObjectEncryptionRequired: false grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN idTokenSignAlg: RS256 modifiedAt: 1639468356000 number: 6164 parRequired: false redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false responseTypes: - CODE - TOKEN serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_create_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/create \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "developer": "john", "clientName": "My Client", ... }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); Client client = new Client(); client.setDeveloper("john"); client.setClientName("My Client"); ... api.createClient(client); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) client = Client() client.developer = 'john' client.clientName = 'My Client' ... api.createClient(client) tags: - Client Management /api/{serviceId}/client/update/{clientId}: post: summary: Update Client description: | Update a client. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: A client ID. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/client' example: applicationType: WEB attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authTimeRequired: false bcUserCodeRequired: false clientIdAlias: my-client clientIdAliasEnabled: true clientName: My updated client clientType: CONFIDENTIAL defaultMaxAge: 0 derivedSectorIdentifier: my-client.example.com developer: john dynamicallyRegistered: false frontChannelRequestObjectEncryptionRequired: false grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN idTokenSignAlg: RS256 parRequired: false redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false responseTypes: - CODE - TOKEN subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/client' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client' example: applicationType: WEB attributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value authTimeRequired: false bcUserCodeRequired: false clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My updated client clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ clientType: CONFIDENTIAL createdAt: 1639468356000 defaultMaxAge: 0 derivedSectorIdentifier: my-client.example.com developer: john dynamicallyRegistered: false frontChannelRequestObjectEncryptionRequired: false grantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN idTokenSignAlg: RS256 modifiedAt: 1639557082764 number: 6164 parRequired: false redirectUris: - https://my-client.example.com/cb1 - https://my-client.example.com/cb2 requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false responseTypes: - CODE - TOKEN serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': description: The client was not found. '500': $ref: '#/components/responses/500' operationId: client_update_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/update/26478243745571 \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "clientName": "My updated client", ... }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); // Get an existing client. long clientId = ...; Client client = api.getClient(clientId); // Update "client name". client.setClientName("My updated client"); api.updateClient(client); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) # Get an existing client. clientId = ... client = api.getClient(clientId) # Update "client name". client.clientName = 'My updated client' api.updatedClient(client) tags: - Client Management /api/{serviceId}/client/delete/{clientId}: delete: summary: Delete Client ⚑ description: | Delete a client. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: The client ID. responses: '204': description: The client was successfully deleted. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': description: The client was not found. '500': $ref: '#/components/responses/500' operationId: client_delete_api x-code-samples: - lang: shell label: curl source: | curl -v -X DELETE https://us.authlete.com/api/21653835348762/client/delete/26478243745571 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = ...; api.deleteClient(clientId); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = ... api.deleteClient(clientId) tags: - Client Management /api/{serviceId}/client/lock_flag/update/{clientIdentifier}: post: summary: Update Client Lock description: | Lock and unlock a client parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientIdentifier schema: type: string required: true description: A client ID. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/client_flag_update_request' example: clientLocked: true application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/client_flag_update_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_flag_update_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_flag_update_api tags: - Client Management /api/{serviceId}/client/secret/refresh/{clientIdentifier}: get: summary: Rotate Client Secret description: | Refresh the client secret of a client. A new value of the client secret will be generated by the Authlete server. If you want to specify a new value, use `/api/client/secret/update` API. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientIdentifier schema: type: string required: true description: | The client ID or the client ID alias of a client. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_secret_refresh_response' example: resultCode: A148001 resultMessage: '[A148001] Successfully refreshed the client secret of the client (ID = 26478243745571).' newClientSecret: 6Rg_WDO23F0HSZe8GzE5_ZxRHD2pCA02M7T87s0MNOmnf8hg9eYScgeH6P_tb42yiaRuptJmMY12jwWuoy2KeA oldClientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_secret_refresh_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/client/secret/refresh/26478243745571 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); String clientIdentifier = ...; api.refreshClientSecret(clientIdentifier); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientIdentifier = ... api.refreshClientSecret(clientIdentifier) tags: - Client Management /api/{serviceId}/client/secret/update/{clientIdentifier}: post: summary: Update Client Secret description: | Update the client secret of a client. If you want to have the Authlete server generate a new value of the client secret, use `/api/client/secret/refresh` API. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientIdentifier schema: type: string required: true description: | The client ID or the client ID alias of a client. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/client_secret_update_request' example: clientSecret: my_updated_client_secret application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/client_secret_update_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_secret_update_response' example: resultCode: A149001 resultMessage: '[A149001] Successfully updated the client secret of the client (ID = 26478243745571).' newClientSecret: my_updated_client_secret oldClientSecret: 6Rg_WDO23F0HSZe8GzE5_ZxRHD2pCA02M7T87s0MNOmnf8hg9eYScgeH6P_tb42yiaRuptJmMY12jwWuoy2KeA '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_secret_update_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/client/secret/update/26478243745571 \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "clientSecret": "..." }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); String clientIdentifier = ...; String clientSecret = "my_updated_client_secret"; api.updateClientSecret(clientIdentifier, clientSecret); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientIdentifier = ... clientSecret = 'my_new_client_secret' api.updateClientSecret(clientIdentifier, clientSecret) tags: - Client Management /api/{serviceId}/client/authorization/get/list: get: summary: Get Authorized Applications description: | Get a list of client applications that an end-user has authorized. The subject parameter is required and can be provided as a query parameter. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: query name: subject schema: type: string required: true description: | Unique user ID of an end-user. - in: query name: developer schema: type: string required: false description: | Unique ID of a client developer. - in: query name: start schema: type: integer format: int32 required: false description: Start index of search results (inclusive). The default value is 0. - in: query name: end schema: type: integer format: int32 required: false description: | End index of search results (exclusive). The default value is 5. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_get_list_response' example: clients: - clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My client clientType: CONFIDENTIAL number: 6164 end: 5 start: 0 subject: john totalCount: 1 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_authorization_get_list_api tags: - Client Management post: summary: Get Authorized Applications description: | Get a list of client applications that an end-user has authorized. The subject parameter is required. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/client_authorization_get_list_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/client_authorization_get_list_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_get_list_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_authorization_get_list_api_post tags: - Client Management x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/client/authorization/get/list?subject=john\&start=0\&end=5 \ -u '21653835348762:uE4NgqeIpuSV_XejQ7Ds3jsgA1yXhjR1MXJ1LbPuyls' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); ClientAuthorizationGetListRequest req = new ClientAuthorizationGetListRequest(); req.setSubject("john"); req.setStart(0); req.setEnd(5); api.getClientAuthorizationList(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = ClientAuthorizationGetListRequest() req.subject = 'john' req.start = 0 req.end = 5 api.getClientAuthorizationList(req) /api/{serviceId}/client/authorization/get/list/{subject}: get: summary: Get Authorized Applications (by Subject) description: | Get a list of client applications that an end-user has authorized. In this variant, the subject is provided in the path. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: subject schema: type: string required: true description: | Unique user ID of an end-user. - in: query name: developer schema: type: string required: false description: | Unique ID of a client developer. - in: query name: start schema: type: integer format: int32 required: false description: Start index of search results (inclusive). The default value is 0. - in: query name: end schema: type: integer format: int32 required: false description: | End index of search results (exclusive). The default value is 5. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_get_list_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_authorization_get_list_by_subject_api tags: - Client Management /api/{serviceId}/client/authorization/update/{clientId}: post: summary: Update Client Tokens description: | Update attributes of all existing access tokens given to a client application. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/client_authorization_update_request' example: subject: john scopes: - history.read application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/client_authorization_update_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_update_response' example: resultCode: A138001 resultMessage: '[A138001] Updated 1 access token(s) issued to the client (ID = 26478243745571) of the service (API Key = 21653835348762).' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': description: The client was not found. '500': $ref: '#/components/responses/500' operationId: client_authorization_update_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/authorization/update/26478243745571 \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "subject": "john", "scopes": [ "history.read" ] }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = ...; ClientAuthorizationUpdateRequest req = new ClientAuthorizationUpdateRequest(); req.setSubject("john"); req.setScopes(new String[]{ "history.read" }); api.updateClientAuthorization(clientId, req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = ... req = ClientAuthorizationUpdateRequest() req.subject = 'john' req.scopes = [ 'history.read' ] api.updateClientAuthorization(clientId, req) tags: - Client Management /api/{serviceId}/client/authorization/delete/{clientId}: delete: summary: Delete Client Tokens description: | Delete all existing access tokens issued to a client application by an end-user. The subject parameter is required and must be provided as a query parameter. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. - in: query name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' example: resultCode: A137001 resultMessage: '[A137001] Deleted 3 access token(s) issued to the client (ID = 26478243745571) of the service (API Key = 21653835348762).' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_authorization_delete_api tags: - Client Management post: summary: Delete Client Tokens description: | Delete all existing access tokens issued to a client application by an end-user. The subject parameter is required. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. requestBody: required: true content: application/json: schema: type: object properties: subject: type: string description: Unique user ID of an end-user. required: - subject application/x-www-form-urlencoded: schema: type: object properties: subject: type: string description: Unique user ID of an end-user. required: - subject responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' operationId: client_authorization_delete_api_post tags: - Client Management x-code-samples: - lang: shell label: curl source: | curl -v -X DELETE https://us.authlete.com/api/21653835348762/client/authorization/delete/26478243745571?subject=john \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = ...; String subject = "john"; api.deleteClientAuthorization(clientId, subject); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = ... subject = 'john' api.deleteClientAuthorization(clientId, subject) /api/{serviceId}/client/authorization/delete/{clientId}/{subject}: delete: summary: Delete Client Tokens (by Subject) description: | Delete all existing access tokens issued to a client application by an end-user. In this variant, the subject is provided in the path. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. - in: path name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_authorization_delete_by_subject_api tags: - Client Management /api/{serviceId}/client/granted_scopes/get/{clientId}: get: summary: Get Granted Scopes description: | Get the set of scopes that a user has granted to a client application. x-mint: metadata: description: "Get the set of scopes that a user has granted to a client application." content: | Possible values for `requestableScopes` parameter in the response from this API are as follows. ## null The user has not granted authorization to the client application in the past, or records about the combination of the user and the client application have been deleted from Authlete's DB. ## An empty set The user has granted authorization to the client application in the past, but no scopes are associated with the authorization. ## A set with at least one element The user has granted authorization to the client application in the past and some scopes are associated with the authorization. These scopes are returned. Example: `[ "profile", "email" ]` The subject parameter is required and must be provided as a query parameter. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string example: '715948317' - in: path name: clientId schema: type: string required: true description: | A client ID. example: '1140735077' - in: query name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: Successfully retrieved granted scopes content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' example: type: GrantedScopesGetResponse serviceApiKey: 21653835348762 clientId: 26478243745571 subject: john latestGrantedScopes: - history.read mergedGrantedScopes: - history.read - timeline.read '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_granted_scopes_get_api tags: - Client Management post: summary: Get Granted Scopes description: | Get the set of scopes that a user has granted to a client application. The subject parameter is required. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. requestBody: required: true content: application/json: schema: type: object properties: subject: type: string description: Unique user ID of an end-user. required: - subject application/x-www-form-urlencoded: schema: type: object properties: subject: type: string description: Unique user ID of an end-user. required: - subject responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' operationId: client_granted_scopes_get_api_post tags: - Client Management x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/client/granted_scopes/get/26478243745571?subject=john \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = 26478243745571; String subject = "john"; api.getGrantedScopes(clientId, subject); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = 26478243745571 subject = 'john' api.getGrantedScopes(clientId, subject) /api/{serviceId}/client/granted_scopes/get/{clientId}/{subject}: get: summary: Get Granted Scopes (by Subject) description: | Get the set of scopes that a user has granted to a client application. In this variant, the subject is provided in the path. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. - in: path name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: Successfully retrieved granted scopes content: application/json: schema: $ref: '#/components/schemas/client_authorization_delete_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_granted_scopes_get_by_subject_api tags: - Client Management /api/{serviceId}/client/granted_scopes/delete/{clientId}: delete: summary: Delete Granted Scopes description: | Delete the set of scopes that an end-user has granted to a client application. Even if records about granted scopes are deleted by calling this API, existing access tokens are not deleted and scopes of existing access tokens are not changed. The subject parameter is required and must be provided as a query parameter. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. - in: query name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_granted_scopes_delete_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_granted_scopes_delete_api x-code-samples: - lang: shell label: curl source: | curl -v -X DELETE https://us.authlete.com/api/21653835348762/client/granted_scopes/delete/26478243745571?subject=john \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); long clientId = ...; String subject = "john"; api.deleteGrantedScopes(clientId, subject); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientId = ... subject = 'john' api.deleteClientAuthorization(clientId, subject) tags: - Client Management /api/{serviceId}/client/granted_scopes/delete/{clientId}/{subject}: delete: summary: Delete Granted Scopes (by Subject) description: | Delete the set of scopes that an end-user has granted to a client application. In this variant, the subject is provided in the path. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. - in: path name: subject schema: type: string required: true description: | Unique user ID of an end-user. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_granted_scopes_delete_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_granted_scopes_delete_by_subject_api tags: - Client Management /api/{serviceId}/auth/authorization: post: summary: Process Authorization Request x-badges: - color: red label: Core API description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. x-mint: metadata: description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." content: | This API is supposed to be called from within the implementation of the authorization endpoint of the service. The endpoint implementation must extract the request parameters from the authorization request from the client application and pass them as the value of parameters request parameter for Authlete's `/auth/authorization` API. The value of `parameters` is either (1) the entire query string when the HTTP method of the request from the client application is `GET` or (2) the entire entity body (which is formatted in `application/x-www-form-urlencoded`) when the HTTP method of the request from the client application is `POST`. The following code snippet is an example in JAX-RS showing how to extract request parameters from the authorization request. ```java @GET public Response get(@Context UriInfo uriInfo) { // The query parameters of the authorization request. String parameters = uriInfo.getRequestUri().getQuery(); ...... } @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post(String parameters) { // 'parameters' is the entity body of the authorization request. ...... } ``` The endpoint implementation does not have to parse the request parameters from the client application because Authlete's `/auth/authorization` API does it. The response from `/auth/authorization` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. A response with HTTP status of "400 Bad Request" should be returned to the client application and Authlete recommends `application/json` as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "400 Bad Request" is not required by OAuth 2.0. ## LOCATION When the value of `action` is `LOCATION`, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined. A response with HTTP status of "302 Found" must be returned to the client application with `Location` header which has a redirect URI with error parameter. The value of `responseContent` is a redirect URI with `error` parameter, so it can be used as the value of `Location` header. The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 302 Found Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the request from the client application is invalid but the redirect URI to which the error should be reported has been determined, and that the authorization request contains `response_mode=form_post` as is defined in [OAuth 2.0 Form Post Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html). The HTTP status of the response returned to the client application should be "200 OK" and the content type should be `text/html;charset=UTF-8`. The value of `responseContent` is an HTML which can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## NO_INTERACTION When the value of `action` is `NO_INTERACTION`, it means that the request from the client application has no problem and requires the service to process the request without displaying any user interface pages for authentication or consent. This case happens when the authorization request contains `prompt=none`. The service must follow the steps described below. **[1] END-USER AUTHENTICATION** Check whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]). Otherwise, call Authlete's `/auth/authorization/fail` API with `reason=NOT_LOGGED_IN` and use the response from the API to generate a response to the client application. **[2] MAX AGE** Get the value of `maxAge` parameter from the `/auth/authorization` API response. The value represents the maximum authentication age which has come from `max_age` request parameter or `defaultMaxAge` configuration parameter of the client application. If the value is `0`, go to the next step ([SUBJECT]). Otherwise, follow the sub steps described below. - (i) Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete, meaning that it is expected that the service implementation manages the value. If the service implementation does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API with `reason=MAX_AGE_NOT_SUPPORTED` and use the API response to generate a response to the client application. - (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication time. The calculated value is the expiration time. - (iii) Check whether the calculated value is equal to or greater than the current time. If this condition is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail` API with `reason=EXCEEDS_MAX_AGE` and use the API response to generate a response to the client application. **[3] SUBJECT** Get the value of `subject` from the `/auth/authorization` API response. The value represents an end-user who the client application expects to grant authorization. If the value is `null`, go to the next step ([ACRs]). Otherwise, follow the sub steps described below. - (i) Compare the value of the requested subject to the current end-user. - (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete's `/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API to generate a response to the client application. **[4] ACRs** Get the value of `acrs` from the `/auth/authorization` API response. The value represents a list of ACRs (Authentication Context Class References) and comes from (1) acr claim in `claims` request parameter, (2) `acr_values` request parameter, or (3) `default_acr_values` configuration parameter of the client application. It is ensured that all the ACRs in acrs are supported by the authorization server implementation. In other words, it is ensured that all the ACRs are listed in `acr_values_supported` configuration parameter of the authorization server. If the value of ACRs is `null`, go to the next step ([ISSUE]). Otherwise, follow the sub steps described below. - (i) Get the ACR performed for the authentication of the current end-user. Note that this value is managed not by Authlete but by the authorization server implementation. (If the authorization server implementation cannot handle ACRs, it should not have listed ACRs as `acr_values_supported`.) - (ii) Compare the ACR value obtained in the above step to each element in the ACR array (`acrs`) in the listed order. - (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the current end-user did not match any one of the ACRs requested by the client application), check whether one of the requested ACRs must be satisfied or not using `acrEssential` parameter in the `/auth/authorization` API response. If the value of `acrEssential` parameter is `true`, call Authlete's `/auth/authorization/fail` API with `reason=ACR_NOT_SATISFIED` and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([SCOPES]). **[5] SCOPES** Get the value of `scopes` from the `/auth/authorization` API response. If the array contains a scope which has not been granted to the client application by the end-user in the past, call Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]). Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*` APIs), which is only available in a dedicated/onpremise Authlete server (contact sales@authlete.com for details). **[6] DYNAMIC SCOPES** Get the value of `dynamicScopes` from the `/auth/authorization` API response. If the array contains a scope which has not been granted to the client application by the end-user in the past, call Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]). Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*` APIs) but dynamic scopes are not remembered as granted scopes. **[7] RESOURCES** Get the value of `resources` from the `/auth/authorization` API response. The array represents the values of the `resource` request parameters. If you want to reject the request, call Authlete's `/auth/authorization/fail` API with `reason=INVALID_TARGET` and use the response from the API to generate a response to the client application. Otherwise, go to the next step ([ISSUE]). See "Resource Indicators for OAuth 2.0" for details. **[8] ISSUE** If all the above steps succeeded, the last step is to issue an authorization code, an ID token and/or an access token. (There is a special case, though. In the case of `response_type=none`, nothing is issued.) It can be performed by calling Authlete's `/auth/authorization/issue` API. The API requires the following parameters. Prepare these parameters and call `/auth/authorization/issue` API and use the response to generate a response to the client application. - `ticket` (required) This parameter represents a ticket which is exchanged with tokens at `/auth/authorization/issue`. Use the value of `ticket` contained in the `/auth/authorization` API response. - `subject` (required) This parameter represents the unique identifier of the current end-user. It is often called "user ID" and it may or may not be visible to the user. In any case, it is a number or a string assigned to an end-user by the authorization server implementation. Authlete does not care about the format of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100. When the value of `subject` parameter in the /auth/authorization API response is not `null`, it is necessarily identical to the value of `subject` parameter in the `/auth/authorization/issue` API request. The value of this parameter will be embedded in an ID token as the value of `sub` claim. When the value of `subject_type` configuration parameter of the client application is `PAIRWISE`, the value of sub claim is different from the value specified by this parameter, See [8. Subject Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) of OpenID Connect Core 1.0 for details about subject types. You can use the `sub` request parameter to adjust the value of the `sub` claim in an ID token. See the description of the `sub` request parameter for details. - `authTime` (optional) This parameter represents the time when the end-user authentication occurred. Its value is the number of seconds from `1970-01-01`. The value of this parameter will be embedded in an ID token as the value of `auth_time` claim. - `acr` (optional) This parameter represents the ACR (Authentication Context Class Reference) which the authentication of the end-user satisfies. When `acrs` in the `/auth/authorization` API response is a non-empty array and the value of `acrEssential` is `true`, the value of this parameter must be one of the array elements. Otherwise, even `null` is allowed. The value of this parameter will be embedded in an ID token as the value of `acr` claim. - `claims` (optional) This parameter represents claims of the end-user. "Claims" here are pieces of information about the end-user such as `"name"`, `"email"` and `"birthdate"`. The authorization server implementation is required to gather claims of the end-user, format the claim values into JSON and set the JSON string as the value of this parameter. The claims which the authorization server implementation is required to gather are listed in `claims` parameter in the `/auth/authorization` API response. For example, if claims parameter lists `"name"`, `"email"` and `"birthdate"`, the value of this parameter should look like the following. ```json { "name": "John Smith", "email": "john@example.com", "birthdate": "1974-05-06" } ``` `claimsLocales` parameter in the `/auth/authorization` API response lists the end-user's preferred languages and scripts, ordered by preference. When `claimsLocales` parameter is a non-empty array, its elements should be taken into account when the authorization server implementation gathers claim values. Especially, note the excerpt below from [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) of OpenID Connect Core 1.0. > When the OP determines, either through the `claims_locales` parameter, or by other means, that the End-User and Client are requesting Claims in only one set of languages and scripts, it is RECOMMENDED that OPs return Claims without language tags when they employ this language and script. It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims using language tags. If `claims` parameter in the `/auth/authorization` API response is `null` or an empty array, the value of this parameter should be `null`. See [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization server implementation support its special claims ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims)) and (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)). Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) for details. The claim values in this parameter will be embedded in an ID token. Note that `idTokenClaims` parameter is available in the `/auth/authorization` API response. The parameter has the value of the `"id_token"` property in the `claims` request parameter or in the `"claims"` property in a request object. The value of this parameter should be considered when you prepare claim values. - `properties` (optional) Extra properties to associate with an access token and/or an authorization code that may be issued by this request. Note that `properties` parameter is accepted only when `Content-Type` of the request is `application/json`, so don't use `application/x-www-form-urlencoded` for details. - `scopes` (optional) Scopes to associate with an access token and/or an authorization code. If this parameter is `null`, the scopes specified in the original authorization request from the client application are used. In other cases, including the case of an empty array, the specified scopes will replace the original scopes contained in the original authorization request. Even scopes that are not included in the original authorization request can be specified. However, as an exception, `openid` scope is ignored on the server side if it is not included in the original request. It is because the existence of `openid` scope considerably changes the validation steps and because adding `openid` triggers generation of an ID token (although the client application has not requested it) and the behavior is a major violation against the specification. If you add `offline_access` scope although it is not included in the original request, keep in mind that the specification requires explicit consent from the user for the scope ([OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)). When `offline_access` is included in the original request, the current implementation of Authlete's `/auth/authorization` API checks whether the request has come along with `prompt` request parameter and the value includes consent. However, note that the implementation of Authlete's `/auth/authorization/issue` API does not perform such checking if `offline_access` scope is added via this `scopes` parameter. - `sub` (optional) The value of the `sub` claim in an ID token. If the value of this request parameter is not empty, it is used as the value of the `sub` claim. Otherwise, the value of the `subject` request parameter is used as the value of the `sub` claim. The main purpose of this parameter is to hide the actual value of the subject from client applications. Note that even if this `sub` parameter is not empty, the value of the subject request parameter is used as the value of the subject which is associated with the access token. ## INTERACTION When the value of `action` is `INTERACTION`, it means that the request from the client application has no problem and requires the service to process the request with user interaction by an HTML form. The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to the client application. The items described below are some points which the service implementation should take into account when it builds the UI. **[1] DISPLAY MODE** The response from `/auth/authorization` API has `display` parameter. It is one of `PAGE` (default), `POPUP`, `TOUCH` and `WAP` The meanings of the values are described in [3.1.2.1. Authentication Request of OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Basically, the authorization server implementation should display the UI which is suitable for the display mode, but it is okay for the authorization server implementation to "attempt to detect the capabilities of the User Agent and present an appropriate display". It is ensured that the value of `display` is one of the supported display modes which are specified by `supportedDisplays` configuration parameter of the service. **[2] UI LOCALE** The response from `/auth/authorization` API has `uiLocales` parameter. It it is not `null`, it lists language tag values (such as `fr-CA`, `ja-JP` and `en`) ordered by preference. The service implementation should display the UI in one of the language listed in the parameter when possible. It is ensured that language tags listed in `uiLocales` are contained in the list of supported UI locales which are specified by `supportedUiLocales` configuration parameter of the service. **[3] CLIENT INFORMATION** The authorization server implementation should show information about the client application to the end-user. The information is embedded in `client` parameter in the response from `/auth/authorization` API. **[4] SCOPES** A client application requires authorization for specific permissions. In OAuth 2.0 specification, "scope" is a technical term which represents a permission. `scopes` parameter in the response from `/auth/authorization` API is a list of scopes requested by the client application. The service implementation should show the end-user the scopes. The authorization server implementation may choose not to show scopes to which the end-user has given consent in the past. To put it the other way around, the authorization server implementation may show only the scopes to which the end-user has not given consent yet. However, if the value of `prompts` response parameter contains `CONSENT`, the authorization server implementation has to obtain explicit consent from the end-user even if the end-user has given consent to all the requested scopes in the past. Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*` APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server (contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server are disabled intentionally (in order to prevent garbage data from being accumulated) and they return 403 Forbidden. It is ensured that the values in `scopes` parameter are contained in the list of supported scopes which are specified by `supportedScopes` configuration parameter of the service. **[5] DYNAMIC SCOPES** The authorization request may include dynamic scopes. The list of recognized dynamic scopes are accessible by getDynamicScopes() method. See the description of the [DynamicScope](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html) class for details about dynamic scopes. **[6] AUTHORIZATION DETAILS** The authorization server implementation should show the end-user "authorization details" if the request includes it. The value of `authorization_details` parameter in the response is the content of the `authorization_details` request parameter. See "OAuth 2.0 Rich Authorization Requests" for details. **[7] PURPOSE** The authorization server implementation must show the value of the `purpose` request parameter if it supports [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8) in the specification for details. Note that the value of `purpose` response parameter is the value of the purpose request parameter. **[7] END-USER AUTHENTICATION** Necessarily, the end-user must be authenticated (= must login the service) before granting authorization to the client application. Simply put, a login form is expected to be displayed for end-user authentication. The service implementation must follow the steps described below to comply with OpenID Connect. (Or just always show a login form if it's too much of a bother.) - (i) Get the value of `prompts` response parameter. It corresponds to the value of the `prompt` request parameter. Details of the request parameter are described in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of OpenID Connect Core 1.0. - (ii) If the value of `prompts` parameter is `SELECT_ACCOUNT` display a form to let the end-user select on of his/her accounts for login. If `subject` response parameter is not `null`, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint` response parameter should be referred to as a hint to determine the value of the login ID. The value of `loginHint` response parameter is simply the value of the `login_hint` request parameter. - (iii) If the value of `prompts` response parameter contains `LOGIN`, display a form to urge the end-user to login even if the end-user has already logged in. If the value of `subject` response parameter is not `null`, it is the end-user ID that the client application expects, so the value should be used to determine the value of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint` response parameter should be referred to as a hint to determine the value of the login ID. The value of `loginHint` response parameter is simply the value of the `login_hint` request parameter. - (iv) If the value of `prompts` response parameter does not contain `LOGIN`, the authorization server implementation does not have to authenticate the end-user if all the conditions described below are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate the end-user. - An end-user has already logged in the service. - The login ID of the current end-user matches the value of `subject` response parameter. This check is required only when the value of `subject` response parameter is a non-null value. - The max age, which is the number of seconds contained in `maxAge` response parameter, has not passed since the current end-user logged in your service. This check is required only when the value of `maxAge` response parameter is a non-zero value. - If the authorization server implementation does not manage authentication time of end-users (= if the authorization server implementation cannot know when end-users logged in) and if the value of `maxAge` response parameter is a non-zero value, a login form should be displayed. - The ACR (Authentication Context Class Reference) of the authentication performed for the current end-user satisfies one of the ACRs listed in `acrs` response parameter. This check is required only when the value of `acrs` response parameter is a non-empty array. In every case, the end-user authentication must satisfy one of the ACRs listed in `acrs` response parameter when the value of `acrs` response parameter is a non-empty array and `acrEssential` response parameter is `true`. **[9] GRANT/DENY BUTTONS** The end-user is supposed to choose either (1) to grant authorization to the client application or (2) to deny the authorization request. The UI must have UI components to accept the judgment by the user. Usually, a button to grant authorization and a button to deny the request are provided. When the value of `subject` response parameter is not `null`, the end-user authentication must be performed for the subject, meaning that the authorization server implementation should repeatedly show a login form until the subject is successfully authenticated. The end-user will choose either (1) to grant authorization to the client application or (2) to deny the authorization request. When the end-user chose to deny the authorization request, call Authlete's `/auth/authorization/fail` API with `reason=DENIED` and use the response from the API to generate a response to the client application. When the end-user chose to grant authorization to the client application, the authorization server implementation has to issue an authorization code, an ID token, and/or an access token to the client application. (There is a special case. When `response_type=none`, nothing is issued.) Issuing the tokens can be performed by calling Authlete's `/auth/authorization/issue` API. Read [ISSUE] written above in the description for the case of `action=NO_INTERACTION`. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_request' example: parameters: response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_request' responses: '200': description: Authorization request processed successfully content: application/json: schema: $ref: '#/components/schemas/authorization_response' example: resultCode: A004001 resultMessage: '[A004001] Authlete has successfully issued a ticket to the service (API Key = 21653835348762) for the authorization request from the client (ID = 26478243745571). [response_type=code, openid=false]' acrEssential: false action: INTERACTION client: clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My updated client logo_uri: https://my-client.example.com/logo.png number: 6164 clientIdAliasUsed: false display: PAGE maxAge: 0 scopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read service: apiKey: 21653835348762 clientIdAliasEnabled: true number: 5041 serviceName: My updated service ticket: hXoY87t_t23enrVHWxpXNP5FfVDhDypD3T6H6lt4IPA links: authz_issue: $ref: '#/components/links/authz_issue' authz_fail: $ref: '#/components/links/authz_fail' token_exchange: $ref: '#/components/links/token_exchange' token_issue_direct: $ref: '#/components/links/token_issue_direct' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters": "response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationRequest req = new AuthorizationRequest(); req.setParameters(...); api.authorization(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = AuthorizationRequest() req.parameters = ... api.authorization(req) tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/fail: post: summary: Fail Authorization Request x-badges: - color: red label: Core API description: | This API generates a content of an error authorization response that the authorization server implementation returns to the client application. x-mint: metadata: description: "This API generates a content of an error authorization response that the authorization server implementation returns to the client application." content: | This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate an error response to the client application. The description of the `/auth/authorization` API describes the timing when this API should be called. The response from `/auth/authorization/fail` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed response to the authorization UI. A response with HTTP status of "400 Bad Request" should be returned to the client application and Authlete recommends `application/json` as the content type. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "400 Bad Request" is not required by OAuth 2.0. ## LOCATION When the value of `action` is `LOCATION`, it means that the response to the client application must be "302 Found" with Location header. The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token and/or an access token (on success) or (2) an error code (on failure), so it can be used as the value of `Location` header. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 302 Found Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the response to the client application must be 200 OK with an HTML which triggers redirection by JavaScript. This happens when the authorization request from the client application contained `response_mode=form_post`. The value of `responseContent` is an HTML which can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_fail_request' example: ticket: qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ reason: NOT_AUTHENTICATED application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_fail_response' example: resultCode: A004201 resultMessage: '[A004201] The authorization request from the service does not contain ''parameters'' parameter.' action: BAD_REQUEST responseContent: '{\"error_description\":\"[A004201] The authorization request from the service does not contain ''parameters'' parameter.\",\"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A004201\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_fail_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization/fail \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q", "reason": "NOT_AUTHENTICATED" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationFailRequest req = new AuthorizationFailRequest(); req.setTicket("c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q"); req.setReason(AuthorizationFailRequest.Reason.NOT_AUTHENTICATED); api.authorizationFail(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = AuthorizationFailRequest() req.ticket = 'c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q' req.reason = AuthorizationFailReason.NOT_AUTHENTICATED api.authorizationFail(req) tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/issue: post: summary: Issue Authorization Response x-badges: - color: red label: Core API description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. x-mint: metadata: description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." content: | This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate a successful response to the client application. The description of the `/auth/authorization` API describes the timing when this API should be called and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`. The response from `/auth/authorization/issue` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of "action" is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed response to the authorization UI. The HTTP status of the response returned to the client application should be "400 Bad Request" and the content type should be `application/json` although OAuth 2.0 specification does not mention the format of the error response. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "400 Bad Request" is not required by OAuth 2.0. ## LOCATION When the value of `action` is `LOCATION`, it means that the response to the client application should be "302 Found" with `Location` header. The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID token and/or an access token (on success) or (2) an error code (on failure), so it can be used as the value of `Location` header. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 302 Found Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the response to the client application should be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization request from the client contains `response_mode=form_post` request parameter. The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_issue_request' example: ticket: FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_issue_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_issue_response' example: resultCode: A040001 resultMessage: '[A040001] The authorization request was processed successfully.' accessTokenDuration: 0 accessTokenExpiresAt: 0 action: LOCATION authorizationCode: Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo responseContent: https://my-client.example.com/cb1?code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&iss=https%3A%2F%2Fmy-service.example.com '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_issue_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization/issue \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc", "subject": "john" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationIssueRequest req = new AuthorizationIssueRequest(); req.setTicket("FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc"); req.setSubject("john"); api.authorizationIssue(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = AuthorizationIssueRequest() req.ticket = 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc' req.subject = 'john' api.authorizationIssue(req) tags: - Authorization Endpoint /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 /api/{serviceId}/auth/token: post: summary: Process Token Request description: | This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. x-mint: metadata: description: "This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further." content: | This API is supposed to be called from with the implementation of the token endpoint of the service. The endpoint implementation must extract the request parameters from the token request from the client application and pass them as the value of parameters request parameter to Authlete's `/auth/token` API. The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the token request. In addition, if the token endpoint of the authorization server implementation supports basic authentication as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3), the client credentials must be extracted from `Authorization` header and they must be passed as `clientId` request parameter and `clientSecret` request parameter to Authlete's `/auth/token` API. The following code snippet is an example in JAX-RS showing how to extract request parameters from the token request and client credentials from Authorization header. ```java @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post( @HeaderParam(HttpHeaders.AUTHORIZATION) String auth, String parameters) { // Convert the value of Authorization header (credentials of // the client application), if any, into BasicCredentials. BasicCredentials credentials = BasicCredentials.parse(auth); // The credentials of the client application extracted from // 'Authorization' header. These may be null. String clientId = credentials == null ? null : credentials.getUserId(); String clientSecret = credentials == null ? null : credentials.getPassword(); // Process the given parameters. return process(parameters, clientId, clientSecret); } ``` The response from `/auth/token` API has some parameters. Among them, it is action parameter that the service implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of action, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## INVALID_CLIENT When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). The description about `invalid_client` shown below is an excerpt from RFC 6749. --- Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the `Authorization` request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching the authentication scheme used by the client. --- In either case, the value of `responseContent` is a JSON string which can be used as the entity body of the response to the client application. --- The following illustrate responses which the service implementation must generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## PASSWORD When the value of `"action"` is `"PASSWORD"`, it means that the request from the client application is valid and `grant_type` is `"password"`. That is, the flow is ["Resource Owner Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3). In this case, {@link #getUsername()} returns the value of `"username"` request parameter and {@link #getPassword()} returns the value of {@code "password"} request parameter which were contained in the token request from the client application. The service implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result. 1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client application. The API requires `"ticket"` request parameter and `"subject"` request parameter. Use the value returned from {@link #getTicket()} method as the value for `"ticket"` parameter. 2. The response from `/auth/token/issue` API ({@link TokenIssueResponse}) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application. 3. When the credentials are invalid, call Authlete's {@code /auth/token/fail} API with `reason=`{@link TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response for the client application. The API requires `"ticket"` request parameter. Use the value returned from {@link #getTicket()} method as the value for `"ticket"` parameter. 4. The response from `/auth/token/fail` API ({@link TokenFailResponse}) contains error information which should be returned to the client application. Use it to generate a response to the client application. ## OK When the value of `action` is `OK`, it means that the request from the client application is valid and an access token, and optionally an ID token, is ready to be issued. The HTTP status of the response returned to the client application must be "200 OK" and the content type must be `application/json`. The value of `responseContent` is a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## TOKEN_EXCHANGE (Authlete 2.3 onwards) When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means that the request from the client application is a valid token exchange request (cf. [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed the following validation steps. 1. Confirm that the value of the `requested_token_type` request parameter is one of the registered token type identifiers if the request parameter is given and its value is not empty. 2. Confirm that the `subject_token` request parameter is given and its value is not empty. 3. Confirm that the `subject_token_type` request parameter is given and its value is one of the registered token type identifiers. 4. Confirm that the `actor_token_type` request parameter is given and its value is one of the registered token type identifiers if the `actor_token` request parameter is given and its value is not empty. 5. Confirm that the `actor_token_type` request parameter is not given or its value is empty when the `actor_token` request parameter is not given or its value is empty. Furthermore, Authlete performs additional validation on the tokens specified by the `subject_token` request parameter and the `actor_token` request parameter according to their respective token types as shown below. ## Token Validation Steps \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\* 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html]. 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself when one is used as an input token with the token type { @code "urn:ietf:params:oauth:token-type:jwt" }. 3. Confirm that the current time has not reached the time indicated by the `exp` claim if the JWT contains the claim. 4. Confirm that the current time is equal to or after the time indicated by the `iat` claim if the JWT contains the claim. 5.Confirm that the current time is equal to or after the time indicated by the `nbf` claim if the JWT contains the claim. 6. Check if the JWT is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the input token. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself when a signed JWT is used as an input token with the token type `"urn:ietf:params:oauth:token-type:jwt"`. \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\* 1. Confirm that the token is an access token that has been issued by the Authlete server of your service. This implies that access tokens issued by other systems cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:access_token`. 2. Confirm that the access token has not expired. 3. Confirm that the access token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\* 1. Confirm that the token is a refresh token that has been issued by the Authlete server of your service. This implies that refresh tokens issued by other systems cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:refresh_token`. 2. Confirm that the refresh token has not expired. 3. Confirm that the refresh token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\* 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). 2. Check if the ID Token is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted ID Token because there is no standard way to obtain the key to decrypt the ID Token with in the context of token exchange where the client ID for the encrypted ID Token cannot be determined. This means that you must verify an encrypted ID Token by yourself when one is used as an input token with the token type `"urn:ietf:params:oauth:token-type:id_token"`. 3. Confirm that the ID Token contains the `exp` claim and the current time has not reached the time indicated by the claim. 4. Confirm that the ID Token contains the `iat` claim and the current time is equal to or after the time indicated by the claim. 5. Confirm that the current time is equal to or after the time indicated by the `nbf` claim if the ID Token contains the claim. 6. Confirm that the ID Token contains the `iss` claim and the value is a valid URI. In addition, confirm that the URI has the `https` scheme, no query component and no fragment component. 7. Confirm that the ID Token contains the `aud` claim and its value is a JSON string or an array of JSON strings. 8. Confirm that the value of the `nonce` claim is a JSON string if the ID Token contains the claim. 9. Check if the ID Token is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the input token. 10. Confirm that the signature algorithm is asymmetric. This implies that ID Tokens whose signature algorithm is symmetric (`HS256`, `HS384` or `HS512`) cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:id_token`. 11. Verify the signature of the ID Token. Signature verification is performed even in the case where the issuer of the ID Token is not your service. But in that case, the issuer must support the discovery endpoint defined in [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails. \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\* (Authlete does not perform any validation for this token type.) \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\* (Authlete does not perform any validation for this token type.) The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very flexible. In other words, the specification has abandoned the task of determining details. Therefore, for secure token exchange, you have to complement the specification with your own rules. For that purpose, Authlete provides some configuration options as listed below. Authorization server implementers may utilize them and/or implement their own rules. In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link #getResponseContent()} method returns `null`. You have to construct the token response by yourself. For example, you may generate an access token by calling Authlete's `/api/auth/token/create` API and construct a token response like below. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-cache, no-store { "access_token": "{@link TokenCreateResponse#getAccessToken()}", "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", "token_type": "Bearer", "expires_in": { @link TokenCreateResponse#getExpiresIn() }, "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" } ``` ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards) When the value of `"action"` is `"JWT_BEARER"`, it means that the request from the client application is a valid token request with the grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html)) and that the request has already passed the following validation steps. 1. Confirm that the `assertion` request parameter is given and its value is not empty. 2. Confirm that the format of the assertion conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token request when the {@link Service#isJwtGrantEncryptedJwtRejected() jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself. 4. Confirm that the JWT contains the `iss` claim and its value is a JSON string. 5. Confirm that the JWT contains the `sub` claim and its value is a JSON string. 6. Confirm that the JWT contains the `aud` claim and its value is either a JSON string or an array of JSON strings. 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()}) or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()}) is listed as audience in the `aud` claim. 8. Confirm that the JWT contains the `exp` claim and the current time has not reached the time indicated by the claim. 9. Confirm that the current time is equal to or after the time indicated by by the `iat` claim if the JWT contains the claim. 10. Confirm that the current time is equal to or after the time indicated by by the `nbf` claim if the JWT contains the claim. 11. Check if the JWT is signed and if it is not signed, then (a) reject the token request when the {@link Service#isJwtGrantUnsignedJwtRejected() jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the JWT. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself. Authlete provides some configuration options for the grant type as listed below. Authorization server implementers may utilize them and/or implement their own rules. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-cache, no-store { "access_token": "{@link TokenCreateResponse#getAccessToken()}", "token_type": "Bearer", "expires_in": {@link TokenCreateResponse#getExpiresIn()}, "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" } ``` Finally, note again that Authlete does not verify the signature of the JWT specified by the `assertion` request parameter. You must verify the signature by yourself. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_request' example: parameters: grant_type=authorization_code&code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk clientId: '26478243745571' clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_request' responses: '200': description: Token operation completed successfully content: application/json: schema: $ref: '#/components/schemas/token_response' example: resultCode: A050001 resultMessage: '[A050001] The token request (grant_type=authorization_code) was processed successfully.' accessToken: C4SrUTijIj2IxqE1xBASr3dxQWgso3BpY49g8CyjGjQ accessTokenDuration: 3600 accessTokenExpiresAt: 1640252942736 action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false grantType: AUTHORIZATION_CODE refreshToken: 60k0cZ38sJcpTgdxvG9Sqa-3RG5AmGExGpFB-1imSxo refreshTokenDuration: 3600 refreshTokenExpiresAt: 1640252942736 responseContent: '{\"access_token\":\"C4SrUTijIj2IxqE1xBASr3dxQWgso3BpY49g8CyjGjQ\",\"refresh_token\":\"60k0cZ38sJcpTgdxvG9Sqa-3RG5AmGExGpFB-1imSxo\",\"scope\":\"history.read timeline.read\",\"token_type\":\"Bearer\",\"expires_in\":3600}' scopes: - history.read - timeline.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters": "grant_type=authorization_code&code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "clientId": "57297408867", "clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenRequest req = new TokenRequest(); req.setParameters(...); req.setClientId("57297408867"); req.setClientSecret("J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A"); api.token(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenRequest() req.parameters = ... req.clientId = '57297408867' req.clientSecret = 'J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A' api.token(req) tags: - Token Endpoint /api/{serviceId}/auth/token/fail: post: summary: Fail Token Request description: | This API generates a content of an error token response that the authorization server implementation returns to the client application. x-mint: metadata: description: "This API generates a content of an error token response that the authorization server implementation returns to the client application." content: | This API is supposed to be called from within the implementation of the token endpoint of the service in order to generate an error response to the client application. The description of the `/auth/token` API describes the timing when this API should be called. See the description for the case of `action=PASSWORD`. The response from `/auth/token/fail` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that Authlete's `/auth/token/fail` API successfully generated an error response for the client application. The HTTP status of the response returned to the client application must be "400 Bad Request" and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_fail_request' example: ticket: 83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c reason: INVALID_RESOURCE_OWNER_CREDENTIALS application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/token_fail_response' example: resultCode: A067301 resultMessage: '[A067301] The credentials (username & password) passed to the token endpoint are invalid.' action: BAD_REQUEST responseContent: '{\"error_description\":\"[A067301] The credentials (username & password) passed to the token endpoint are invalid.\",\"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A067301\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_fail_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/fail \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c", "reason": "INVALID_RESOURCE_OWNER_CREDENTIALS" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenFailRequest req = new TokenFailRequest(); req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"); req.setReason(TokenFailRequest.Reason.INVALID_RESOURCE_OWNER_CREDENTIALS); api.tokenFail(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenFailRequest() req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c' req.reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS api.tokenFail(req) tags: - Token Endpoint /api/{serviceId}/auth/token/issue: post: summary: Issue Token Response description: | This API generates a content of a successful token response that the authorization server implementation returns to the client application. x-mint: metadata: description: "This API generates a content of a successful token response that the authorization server implementation returns to the client application." content: | This API is supposed to be called from within the implementation of the token endpoint of the service in order to generate a successful response to the client application. The description of the `/auth/token` API describes the timing when this API should be called. See the description for the case of `action=PASSWORD`. The response from `/auth/token/issue` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## OK When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully generated an access token. The HTTP status of the response returned to the client application must be "200 OK" and the content type must be`application/json`. The value of `responseContent` is a JSON string which contains an access token, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_issue_request' example: ticket: p7SXQ9JFjng7KFOZdCMBKcoR3ift7B54l1LGIgQXqEM subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_issue_request' responses: '200': description: Token issued successfully content: application/json: schema: $ref: '#/components/schemas/token_issue_response' example: resultCode: A054001 resultMessage: '[A054001] The token request (grant_type=password) was processed successfully.' accessToken: OthV6TlZ2pPUtlBBvBSGFYzSdgVy87SSIPz2Zjwi-m0 accessTokenDuration: 3600 accessTokenExpiresAt: 1640331371876 action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false refreshToken: ICPN0-sG3BH4szqiNqaFHZrWUGt7e0zaPuhys3ejQow refreshTokenDuration: 3600 refreshTokenExpiresAt: 1640331371876 responseContent: '{\"access_token\":\"OthV6TlZ2pPUtlBBvBSGFYzSdgVy87SSIPz2Zjwi-m0\",\"refresh_token\":\"ICPN0-sG3BH4szqiNqaFHZrWUGt7e0zaPuhys3ejQow\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":3600}' serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_issue_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/issue \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "p7SXQ9JFjng7KFOZdCMBKcoR3ift7B54l1LGIgQXqEM", "subject": "john" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenIssueRequest req = new TokenIssueRequest() req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"); api.tokenIssue(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenIssueRequest() req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c' api.tokenIssue(req) tags: - Token Endpoint /api/{serviceId}/auth/introspection: post: summary: Process Introspection Request description: | This API gathers information about an access token. x-mint: metadata: description: "This API gathers information about an access token." content: | This API is supposed to be called from within the implementations of protected resource endpoints of the authorization server implementation in order to get information about the access token which was presented by the client application. In general, a client application accesses a protected resource endpoint of a service with an access token, and the implementation of the endpoint checks whether the presented access token has enough privileges (= scopes) to access the protected resource before returning the protected resource to the client application. To achieve this flow, the endpoint implementation has to know detailed information about the access token. Authlete `/auth/introspection` API can be used to get such information. The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is Bearer), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain `token` request parameter). A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be `application/json`. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has expired. The value of `responseContent` is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORBIDDEN When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required scopes or that the subject associated with the access token is different from the subject contained in the request. A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be `application/json`. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is Bearer), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 403 Forbidden WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## OK When the value of `action` is `OK`, it means that the access token which the client application presented is valid (= exists and has not expired). The implementation of the protected resource endpoint is supposed to return the protected resource to the client application. When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate "400 Bad Request". The implementation of the protected resource endpoint may use this string to tell the client application that the request was bad (e.g. in case necessary request parameters for the protected resource endpoint are missing). However, in such a case, the implementation should generate a more informative error message to help developers of client applications. The following is an example error response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` Basically, The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However, if the service has selected another different token type, the service has to generate error messages for itself. _**JWT-based access token**_ Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service (see the description of the Service class for details). `/api/auth/introspection` API can accept access tokens in JWT format. However, note that the API does not return information contained in a given JWT-based access token but returns information stored in the database record which corresponds to the given JWT-based access token. Because attributes of the database record can be modified after the access token is issued (for example, by using `/api/auth/token/update` API), information returned by `/api/auth/introspection` API and information the given JWT-based access token holds may be different. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/introspection_request' example: token: VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI subject: john scopes: - history.read - timeline.read application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/introspection_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/introspection_response' example: resultCode: A056001 resultMessage: '[A056001] The access token is valid.' action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false existent: true expiresAt: 1640416873000 refreshable: true responseContent: Bearer error="invalid_request" scopes: - history.read - timeline.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john sufficient: true usable: true '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_introspection_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "token": "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI", "scopes": [ "history.read", "timeline.read" ] }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); IntrospectionRequest req = new IntrospectionRequest(); req.setToken("VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI"); req.setScopes(new String[] { "history.read", "timeline.read" }); api.introspection(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = IntrospectionRequest() req.token = 'VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI' req.scopes = [ 'history.read', 'timeline.read' ] api.introspection(req) tags: - Introspection Endpoint /api/{serviceId}/auth/introspection/standard: post: summary: Process OAuth 2.0 Introspection Request description: | This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection). x-mint: metadata: description: "This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection)." content: | This API is supposed to be called from within the implementations of the introspection endpoint of your service. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. In general, a client application accesses a protected resource endpoint of a service with an access token, and the implementation of the endpoint checks whether the presented access token has enough privileges (= scopes) to access the protected resource before returning the protected resource to the client application. To achieve this flow, the endpoint implementation has to know detailed information about the access token. Authlete `/auth/introspection` API can be used to get such information. The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response body of error responses. --- The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. This happens when the request from the client did not include the token request parameter. See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in RFC 7662 for details about requirements for introspection requests. The HTTP status of the response returned to the client application should be "400 Bad Request". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response body of error responses. The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json {responseContent} ``` ## OK When the value of `action` is `OK`, the request from the client application is valid. The HTTP status of the response returned to the client application must be "200 OK" and its content type must be `application/json`. The value of `responseContent` is a JSON string which complies with the introspection response defined in "2.2. Introspection Response" in RFC7662. --- The following illustrates the response which the introspection endpoint of your authorization server implementation should generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json {responseContent} ``` Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some form of authorization to access this endpoint**"_. This means that you have to protect your introspection endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection request does not satisfy authorization requirements imposed by your introspection endpoint. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/standard_introspection_request' example: parameters: token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/standard_introspection_request' responses: '200': description: Token introspection completed successfully content: application/json: schema: $ref: '#/components/schemas/standard_introspection_response' example: 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\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_introspection_standard_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection/standard \ -H "Content-Type:application/json" \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters":"token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); StandardIntrospectionRequest req = new StandardIntrospectionRequest(); req.setParameters(...); api.standardIntrospection(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = StandardIntrospectionRequest() req.parameters = ... api.standardIntrospection(req) tags: - Introspection Endpoint /api/{serviceId}/auth/revocation: post: summary: Process Revocation Request description: | This API revokes access tokens and refresh tokens. x-mint: metadata: description: "This API revokes access tokens and refresh tokens." content: | This API is supposed to be called from within the implementation of the revocation endpoint ([RFC 7009](tools.ietf.org/html/rfc7009)) of the authorization server implementation in order to revoke access tokens and refresh tokens. The response from `/auth/revocation` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## INVALID_CLIENT When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". The description about `invalid_client` shown below is an excerpt from [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749). --- Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the `Authorization` request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching the authentication scheme used by the client. --- In either case, the value of `responseContent` is a JSON string which can be used as the entity body of the response to the client application. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. The HTTP status of the response returned to the client application must be "400 Bad Request" and the content type must be `application/json`. [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009), [2.2.1. Error Respons](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1) states "The error presentation conforms to the definition in [Section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) of [[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)]." The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## OK When the value of `action` is `OK`, it means that the request from the client application is valid and the presented token has been revoked successfully or if the client submitted an invalid token. Note that invalid tokens do not cause an error. See [2.2. Revocation Response](https://datatracker.ietf.org/doc/html/rfc7009#section-2.2) for details. The HTTP status of the response returned to the client application must be 200 OK. If the original request from the client application contains callback request parameter and its value is not empty, the content type should be `application/javascript` and the content should be a JavaScript snippet for JSONP. The value of `responseContent` is JavaScript snippet if the original request from the client application contains callback request parameter and its value is not empty. Otherwise, the value of `responseContent` is `null`. ``` HTTP/1.1 200 OK Content-Type: application/javascript Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/revocation_request' example: parameters: VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token clientId: '26478243745571' clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/revocation_request' responses: '200': description: Token revoked successfully content: application/json: schema: $ref: '#/components/schemas/revocation_response' example: resultCode: A113001 resultMessage: '[A113001] The token has been revoked successfully.' action: OK '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_revocation_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/revocation \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters": "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token", "clientId": "26478243745571", "clientSecret": "gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); RevocationRequest req = new RevocationRequest(); request.setParameters(...); api.revocation(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = RevocationRequest() req.parameters = ... api.revocation(req) tags: - Revocation Endpoint /api/{serviceId}/auth/userinfo: post: summary: Process UserInfo Request description: | This API gathers information about a user. x-mint: metadata: description: "This API gathers information about a user." content: | This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) of the authorization server in order to get information about the user that is associated with an access token. The response from `/auth/userinfo` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 500 Internal Server Error WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain `token` parameter). The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has expired, or is not associated with any subject (= any user account). The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORBIDDEN When the value of `action` is `FORBIDDEN`, it means that the access token does not include the `openid` scope. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 403 Forbidden WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## OK When the value of `action` is `OK`, it means that the access token which the client application presented is valid. To be concrete, it means that the access token exists, has not expired, includes the openid scope, and is associated with a subject (= a user account). What the userinfo endpoint implementation should do next is to collect information about the subject (user) from your database. The value of the `subject` is contained in the subject parameter in the response from this API and the names of data, i.e., the claims names are contained in the claims parameter in the response. For example, if the `subject` parameter is `joe123` and the claims parameter is `[ "given_name", "email" ]`, you need to extract information about joe123's given name and email from your database. Then, call Authlete's `/auth/userinfo/issue` API with the collected information and the access token in order to make Authlete generate an ID token. If an error occurred during the above steps, generate an error response to the client. The response should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the subject associated with the access token does not exist in your database any longer, you may feel like generating a response like below. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: Bearer error="invalid_token", error_description="The subject associated with the access token does not exist." Cache-Control: no-store Pragma: no-cache ``` Also, an error might occur on database access. If you treat the error as an internal server error, then the response would be like the following. ``` HTTP/1.1 500 Internal Server Error WWW-Authenticate: Bearer error="server_error", error_description="Failed to extract information about the subject from the database." Cache-Control: no-store Pragma: no-cache ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/userinfo_request' example: token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/userinfo_request' responses: '200': description: User info retrieved successfully content: application/json: schema: $ref: '#/components/schemas/userinfo_response' example: resultCode: A091001 resultMessage: '[A091001] The access token presented at the userinfo endpoint is valid.' action: OK clientId: '15518267821' clientIdAliasUsed: false scopes: - openid subject: john token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_userinfo_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/userinfo \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); UserInfoRequest req = new UserInfoRequest(); req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"); api.userinfo(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = UserInfoRequest() req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI' api.userinfo(req) tags: - UserInfo Endpoint /api/{serviceId}/auth/userinfo/issue: post: summary: Issue UserInfo Response description: | This API generates an ID token. x-mint: metadata: description: "This API generates an ID token." content: | This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) of the authorization server in order to generate an ID token. Before calling this API, a valid response from `/auth/userinfo` API must be obtained. Then, call this API with the access token contained in the response and the claims values of the user (subject) associated with the access token. See **OK** written in the description of `/auth/userinfo` API for details. The response from `/auth/userinfo/issue` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The parameter `responseContent` returns a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 500 Internal Server Error WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain `token` parameter). The parameter `responseContent` returns a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has expired, or is not associated with any subject (= any user account). The parameter `responseContent` returns a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORBIDDEN When the value of `action` is `FORBIDDEN`, it means that the access token does not include the `openid` scope. The parameter `responseContent` returns a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate` header. The following is an example response which complies with RFC 6750. Note that OpenID Connect Core 1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details. ``` HTTP/1.1 403 Forbidden WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## JSON When the value of `action` is `JSON`, it means that the access token which the client application presented is valid and an ID token was successfully generated in the format of JSON. The userinfo endpoint implementation is expected to generate a response to the client application. The content type of the response must be `application/json` and the response body must be an ID token in JSON format. The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so a response to the client can be built like below. ``` HTTP/1.1 200 OK Cache-Control: no-store Pragma: no-cache Content-Type: application/json;charset=UTF-8 {responseContent} ``` ## JWT When the value of `action` is `JWT`, it means that the access token which the client application presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token) ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)). The userinfo endpoint implementation is expected to generate a response to the client application. The content type of the response must be `application/jwt` and the response body must be an ID token in JWT format. The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response to the client can be built like below. ``` HTTP/1.1 200 OK Cache-Control: no-store Pragma: no-cache Content-Type: application/jwt {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/userinfo_issue_request' example: token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/userinfo_issue_request' responses: '200': description: User info issued successfully content: application/json: schema: $ref: '#/components/schemas/userinfo_issue_response' example: resultCode: A096001 resultMessage: '[A096001] An ID token was generated successfully.' action: JSON responseContent: '{\"exp\":1511600971,\"sub\":\"john\",\"aud\":[\"26478243745571\"],\"iss\":\"https://authlete.com\",\"iat\":1511514571}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_userinfo_issue_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/userinfo/issue \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); UserInfoIssueRequest req = new UserInfoIssueRequest(); req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"); api.userinfoIssue(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = UserInfoIssueRequest() req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI' api.userinfoIssue(req) tags: - UserInfo Endpoint /api/{serviceId}/idtoken/reissue: post: summary: Reissue ID Token description: | The API is expected to be called only when the value of the `action` parameter in a response from the `/auth/token` API is [ID_TOKEN_REISSUABLE](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/TokenResponse.Action.html#ID_TOKEN_REISSUABLE). The purpose of the `/idtoken/reissue` API is to generate a token response that includes a new ID token together with a new access token and a refresh token. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/idtoken_reissue_request' responses: '200': description: ID token reissued successfully content: application/json: schema: $ref: '#/components/schemas/idtoken_reissue_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: idtoken_reissue_api tags: - Token Endpoint /api/{serviceId}/gm: post: summary: Process Grant Management Request description: | The API is for the implementation of the grant management endpoint which is defined in "[Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html)". parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/g_m_request' example: accessToken: eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtwyxBgMXQqEPD5q5k9FaEWNk37K8uAtSwrA subject: '123457884' grantId: '57297408867' gmAction: REVOKE responses: '200': description: Grant management completed successfully content: application/json: schema: $ref: '#/components/schemas/g_m_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: grant_m_api tags: - Grant Management Endpoint /api/{serviceId}/service/jwks/get: get: summary: Get JWK Set description: | This API gathers JWK Set information for a service so that its client applications can verify signatures by the service and encrypt their requests to the service. This API is supposed to be called from within the implementation of the jwk set endpoint of the service where the service that supports OpenID Connect must expose its JWK Set information so that client applications can verify signatures by the service and encrypt their requests to the service. The URI of the endpoint can be found as the value of `jwks_uri` in [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) if the service supports [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: query name: includePrivateKeys schema: type: boolean required: false description: The boolean value that indicates whether the response should include the private keys associated with the service or not. If `true`, the private keys are included in the response. The default value is `false`. - in: query name: pretty schema: type: boolean required: false description: This boolean value indicates whether the JSON in the response should be formatted or not. If `true`, the JSON in the response is pretty-formatted. The default value is `false`. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/service_jwks_get_response' example: keys: - e: AQAB 'n': kVXi0XB8LGYZfFPXymaszWjBQsO22tasQH3PEiPeLSymBHbp7PtqM8O8xblqhbxV-24lKNs2zDugQaBiVt4zpalyYxL5kqnfY247priZRfmeUatdECh81T-i3VcLpz_M5yfljfVp3sFdaURUQNA3ow9VtUfvPIxN_9YIxXN1zP2nLP5amC2XA8xMt5iubRwbbPbrLyg69zTOzosDVhRTSs5adHK5HNwVn8wCCZPbU7u1cQD8hFNn8xlQcmOmJjSXUQ9slBpLc7G-dUEOI59RxiPd4R44GtSe8gA1WFXvOAdtGjivSm8BAbxuNO8HFtDJmpVl9YsDr9FsxirFl9ZPKs kty: RSA use: sig kid: rsa-sig-001 - e: AQAB 'n': lQui3_DlrkLs_dyaOQBOclphIIRTTMo0gNlnAgfEM9xjbYQJQzi0CLtO6eseecE3HtvDBWVTw-rMM_NMJTlPTO0_ODWvmJRjXy9DZGEm05LFd_qr6jZ7cdOvjD7zUC3GI9TIokPbjGzueBPJjtAvv_tAazRFCQQfiFy7sQR3u-J4tM8fNo9szo9H09R_eA29llZ3hU39JDKs9nzG60I1mVZtJYPx0_bnO8eYeVDHqoj4SZ4jeru3iX9iDeccH_cDm3M87UomUh-Ri4LlAxXgewDvOaPxAef9ADkDvBVmRo5t60_PJxQ3Tug2EKK-xF1_T7I4TxgS7ga8entMmCxLca kty: RSA use: enc kid: rsa-enc-001 - crv: P-256 kty: EC use: sig 'y': 824At71mYpbGK2oOCKAL1Z2scLPrbVwhM882v3a9gBq x: ZXE3h9BxCyyb_Z9ZJ5qH4Vx650y09qwI1EpZO4o4OmL kid: ec256-sig-001 - crv: P-256 kty: EC use: enc 'y': j80Y3leZHHnxC_gN-Ols_l_VfEBQkfGDFFDG5LNJKMl x: xAdEkaExYWGGAC1xYjwxzvqcaCyDloylZk04yiE9_OF kid: ec256-enc-001 '204': description: No JWK Set available for this service '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_jwks_get_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/service/jwks/get?pretty=true \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); boolean pretty = true; boolean includePrivateKey = false; api.getServiceJwks(pretty, includePrivateKey); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) pretty = True includePrivateKey = False api.getServiceJwks(pretty, includePrivateKey) tags: - JWK Set Endpoint /api/{serviceId}/service/configuration: get: summary: Get Service Configuration description: | This API gathers configuration information about a service. This API is supposed to be called from within the implementation of the configuration endpoint of the service where the service that supports OpenID Connect and [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) must expose its configuration information in a JSON format. Details about the format are described in "[3. OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata)" in OpenID Connect Discovery 1.0. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: query name: pretty schema: type: boolean required: false description: This boolean value indicates whether the JSON in the response should be formatted or not. If `true`, the JSON in the response is pretty-formatted. The default value is `false`. - in: query name: patch schema: type: string required: false description: Get the JSON Patch [RFC 6902 JavaScript Object Notation (JSON) Patch](https://www.rfc-editor.org/rfc/rfc6902) to be applied. responses: '200': description: Service configuration retrieved successfully content: application/json: schema: type: object additionalProperties: true description: | An object representing OpenID Provider configuration information. See [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) and [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) for more details. example: issuer: https://my-service.example.com authorization_endpoint: https://my-service.example.com/authz token_endpoint: https://my-service.example.com/token scopes_supported: - history.read - timeline.read response_types_supported: - code response_modes_supported: - query - fragment - form_post - query.jwt - fragment.jwt - form_post.jwt - jwt grant_types_supported: - authorization_code - password - refresh_token subject_types_supported: - public - pairwise id_token_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA id_token_encryption_alg_values_supported: - RSA1_5 - RSA-OAEP - RSA-OEAP-256 - ECDH-ES - ECDH-ES+A128KW - ECDH-ES+A192KW - ECDH-ES+A256KW - A128KW - A192KW - A256KW - dir - A128GCMKW - A192GCMKW - A256GCMKW - PBES2-HS256+A128KW - PBES2-HS384+A192KW - PBES2-HS512+A256KW id_token_encryption_enc_values_supported: - A128CBC-HS256 - A192CBC-HS384 - A256CBC-HS512 - A128GCM - A192GCM - A256GCM userinfo_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA - none userinfo_encryption_alg_values_supported: - RSA1_5 - RSA-OAEP - RSA-OEAP-256 - ECDH-ES - ECDH-ES+A128KW - ECDH-ES+A192KW - ECDH-ES+A256KW - A128KW - A192KW - A256KW - dir - A128GCMKW - A192GCMKW - A256GCMKW - PBES2-HS256+A128KW - PBES2-HS384+A192KW - PBES2-HS512+A256KW userinfo_encryption_enc_values_supported: - A128CBC-HS256 - A192CBC-HS384 - A256CBC-HS512 - A128GCM - A192GCM - A256GCM request_object_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA request_object_encryption_alg_values_supported: - RSA1_5 - RSA-OAEP - RSA-OEAP-256 - ECDH-ES - ECDH-ES+A128KW - ECDH-ES+A192KW - ECDH-ES+A256KW - A128KW - A192KW - A256KW - dir - A128GCMKW - A192GCMKW - A256GCMKW - PBES2-HS256+A128KW - PBES2-HS384+A192KW - PBES2-HS512+A256KW request_object_encryption_enc_values_supported: - A128CBC-HS256 - A192CBC-HS384 - A256CBC-HS512 - A128GCM - A192GCM - A256GCM authorization_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA authorization_encryption_alg_values_supported: - RSA1_5 - RSA-OAEP - RSA-OEAP-256 - ECDH-ES - ECDH-ES+A128KW - ECDH-ES+A192KW - ECDH-ES+A256KW - A128KW - A192KW - A256KW - dir - A128GCMKW - A192GCMKW - A256GCMKW - PBES2-HS256+A128KW - PBES2-HS384+A192KW - PBES2-HS512+A256KW authorization_encryption_enc_values_supported: - A128CBC-HS256 - A192CBC-HS384 - A256CBC-HS512 - A128GCM - A192GCM - A256GCM token_endpoint_auth_methods_supported: - client_secret_basic token_endpoint_auth_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA display_values_supported: - page claim_types_supported: - normal claims_parameter_supported: true request_parameter_supported: true request_uri_parameter_supported: true require_request_uri_registration: true revocation_endpoint: https://my-service.example.com/revocation revocation_endpoint_auth_methods_supported: [] revocation_endpoint_auth_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA introspection_endpoint: https://my-service.example.com/introspection introspection_endpoint_auth_methods_supported: [] introspection_endpoint_auth_signing_alg_values_supported: - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA code_challenge_methods_supported: - plain - S256 tls_client_certificate_bound_access_tokens: false backchannel_token_delivery_modes_supported: [] backchannel_authentication_request_signing_alg_values_supported: - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA backchannel_user_code_parameter_supported: false require_pushed_authorization_requests: false authorization_details_supported: true verified_claims_supported: false dpop_signing_alg_values_supported: - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 - ES256 - ES384 - ES512 - ES256K - EdDSA require_signed_request_object: false authorization_response_iss_parameter_supported: true '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: service_configuration_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/service/configuration?pretty=true \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); api.getServiceConfiguration(true); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) api.getServiceConfiguration(True) tags: - Service Management /api/{serviceId}/client/registration: post: summary: Register Client description: | Register a client. This API is supposed to be used to implement a client registration endpoint that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol). x-mint: metadata: description: "Register a client. This API is supposed to be used to implement a client registration endpoint that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol)." content: | This API is supposed to be called from the within the implementation of the client registration endpoint of the authorization server. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client or developer, it is an error on the server side. Therefore, the authorization server implementation should generate a response with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client or developer since "500 Internal Server Error" is not required by the specification. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer was wrong. The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## CREATED When the value of `action` is `CREATED`, it means that the request from the client or developer is valid. The authorization server implementation should generate a response to the client or developer with "201 CREATED" and `application/json`. The `responseContent` a JSON string which can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 201 CREATED Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/client_registration_request' - type: object required: - json example: json: '{ "client_name": "My Dynamic Client" }' responses: '200': description: Client registration completed successfully content: application/json: schema: $ref: '#/components/schemas/client_registration_response' example: resultCode: A202001 resultMessage: '[A202001] The client was created with id 26837717140341.' action: CREATED client: authTimeRequired: false bcUserCodeRequired: false clientId: 26837717140341 clientIdAliasEnabled: false clientName: My Dynamic Client clientSecret: bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw clientType: CONFIDENTIAL createdAt: 1641735467000 defaultMaxAge: 0 developer: authlete_21653835348762 dynamicallyRegistered: true frontChannelRequestObjectEncryptionRequired: false idTokenSignAlg: RS256 modifiedAt: 1641735467013 number: 6248 parRequired: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC responseContent: '{\"default_max_age\":0,\"registration_client_uri\":\"https://my-service.example.com/dcr/register/26837717140341\",\"registration_access_token\":\"qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA\",\"client_id\":\"26837717140341\",\"token_endpoint_auth_method\":\"client_secret_basic\",\"require_pushed_authorization_requests\":false,\"backchannel_user_code_parameter\":false,\"client_secret\":\"bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw\",\"client_id_issued_at\":1641735467,\"tls_client_certificate_bound_access_tokens\":false,\"client_name\":\"My Dynamic Client\",\"id_token_signed_response_alg\":\"RS256\",\"subject_type\":\"public\",\"client_secret_expires_at\":0,\"require_signed_request_object\":false}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_registration_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/registration \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "json": "{ \"client_name\": \"My Dynamic Client\" }" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); ClientRegistrationRequest req = new ClientRegistrationRequest(); req.setJson(...); api.dynamicClientRegister(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = new ClientRegistrationRequest() req.json = '...' api.dynamicClientRegister(req) tags: - Dynamic Client Registration /api/{serviceId}/client/registration/get: post: summary: Get Client description: | Get a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). x-mint: metadata: description: "Get a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." content: | This API is supposed to be called from the within the implementation of the client registration management endpoint of the authorization server. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client or developer, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client or developer with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client or developer since "500 Internal Server Error" is not required by the specification. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer was wrong. The authorization server implementation should generate a response to the client or developer with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by the client configuration request (RFC 7592) is invalid, or the client application which the token is tied to does not exist any longer or is invalid. The HTTP status of the response returned to the client application must be "401 Unauthorized" and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the endpoint implementation should generate and return to the client application. ``` HTTP/1.1 401 Unauthorized Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. ## OK When the value of `action` is `OK`, it means that the request from the client or developer is valid. The authorization server implementation should generate a response to the client or developer with "200 OK" and `application/json`. The `responseContent` a JSON string which can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/client_registration_request' - type: object required: - clientId - token example: clientId: '26837717140341' token: qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_registration_response' example: resultCode: A217001 resultMessage: '[A217001] The client information has been returned.' action: OK client: authTimeRequired: false bcUserCodeRequired: false clientId: 26837717140341 clientIdAliasEnabled: false clientName: My Dynamic Client clientSecret: bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw clientType: CONFIDENTIAL createdAt: 1641735467000 defaultMaxAge: 0 developer: authlete_21653835348762 dynamicallyRegistered: true frontChannelRequestObjectEncryptionRequired: false idTokenSignAlg: RS256 modifiedAt: 1641735467000 number: 6248 parRequired: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC responseContent: '{\"default_max_age\":0,\"registration_client_uri\":\"https://my-service.example.com/dcr/register/26837717140341\",\"registration_access_token\":\"qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA\",\"client_id\":\"26837717140341\",\"token_endpoint_auth_method\":\"client_secret_basic\",\"require_pushed_authorization_requests\":false,\"backchannel_user_code_parameter\":false,\"client_secret\":\"bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw\",\"client_id_issued_at\":1641735467,\"tls_client_certificate_bound_access_tokens\":false,\"client_name\":\"My Dynamic Client\",\"id_token_signed_response_alg\":\"RS256\",\"subject_type\":\"public\",\"client_secret_expires_at\":0,\"require_signed_request_object\":false}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_registration_get_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/registration/get \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "clientId": "26837717140341", "token": "qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); ClientRegistrationRequest req = new ClientRegistrationRequest(); req.setClientId("26837717140341"); req.setToken("qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA"); api.dynamicClientGet(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = new ClientRegistrationRequest() req.clientId = '26837717140341' req.token = 'qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA' api.dynamicClientGet(req) tags: - Dynamic Client Registration /api/{serviceId}/client/registration/update: post: summary: Update Client description: | Update a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). x-mint: metadata: description: "Update a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." content: | This API is supposed to be called from the within the implementation of the client registration management endpoint of the authorization server. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client or developer, it is an error on the server side. Therefore, the authorization server implementation should generate a response with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client or developer since "500 Internal Server Error" is not required by the specification. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer was wrong. The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by the client configuration request (RFC 7592) is invalid, or the client application which the token is tied to does not exist any longer or is invalid. The HTTP status of the response returned to the client application must be "401 Unauthorized" and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the endpoint implementation should generate and return to the client application. ``` HTTP/1.1 401 Unauthorized Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. ## UPDATED When the value of `action` is `UPDATED`, it means that the request from the client or developer is valid. The authorization server implementation should generate a response to the client or developer with "200 OK" and `application/json`. The `responseContent` a JSON string which can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/client_registration_request' - type: object required: - clientId - token - json example: clientId: '26837717140341' token: qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA json: '{"client_name":"My Updated Dynamic Client","default_max_age":0,"registration_client_uri":"https://my-service.example.com/dcr/register/26837717140341","client_id":"26837717140341","token_endpoint_auth_method":"client_secret_basic","require_pushed_authorization_requests":false,"backchannel_user_code_parameter":false,"client_secret":"bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw","tls_client_certificate_bound_access_tokens":false,"id_token_signed_response_alg":"RS256","subject_type":"public","require_signed_request_object":false}' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_registration_response' example: resultCode: A213001 resultMessage: '[A213001] The client has been updated.' action: UPDATED client: authTimeRequired: false bcUserCodeRequired: false clientId: 26837717140341 clientIdAliasEnabled: false clientName: My Updated Dynamic Client clientSecret: bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw clientType: CONFIDENTIAL createdAt: 1641735467000 defaultMaxAge: 0 developer: authlete_21653835348762 dynamicallyRegistered: true frontChannelRequestObjectEncryptionRequired: false idTokenSignAlg: RS256 modifiedAt: 1641826276936 number: 6248 parRequired: false requestObjectEncryptionAlgMatchRequired: false requestObjectEncryptionEncMatchRequired: false requestObjectRequired: false serviceNumber: 5041 subjectType: PUBLIC tlsClientCertificateBoundAccessTokens: false tokenAuthMethod: CLIENT_SECRET_BASIC responseContent: '{\"default_max_age\":0,\"registration_client_uri\":\"https://my-service.example.com/dcr/register/26837717140341\",\"registration_access_token\":\"qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA\",\"client_id\":\"26837717140341\",\"token_endpoint_auth_method\":\"client_secret_basic\",\"require_pushed_authorization_requests\":false,\"backchannel_user_code_parameter\":false,\"client_secret\":\"bMsjvZm2FE1_mqJgxhmYj_Wr8rA0Pia_A_j-V076qQm6-P1edKB055W579GBe7MSbOdxZ3dJKsKinCtdIFwxpw\",\"client_id_issued_at\":1641735467,\"tls_client_certificate_bound_access_tokens\":false,\"client_name\":\"My Updated Dynamic Client\",\"id_token_signed_response_alg\":\"RS256\",\"subject_type\":\"public\",\"client_secret_expires_at\":0,\"require_signed_request_object\":false}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_registration_update_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/registration/update \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "clientId": "26837717140341", "token": "qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA", "json": "..." }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); ClientRegistrationRequest req = new ClientRegistrationRequest(); req.setClientId("26837717140341"); req.setToken("qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA"); req.setJson("..."); api.dynamicClientUpdate(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = new ClientRegistrationRequest() req.clientId = '26837717140341' req.token = 'qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA' req.json = '...' api.dynamicClientUpdate(req) tags: - Dynamic Client Registration /api/{serviceId}/client/registration/delete: post: summary: Delete Client description: | Delete a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management). x-mint: metadata: description: "Delete a dynamically registered client. This API is supposed to be used to implement a client registration management endpoint that complies with [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) (OAuth 2.0 Dynamic Registration Management)." content: | This API is supposed to be called from the within the implementation of the client registration management endpoint of the authorization server. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client or developer, it is an error on the server side. Therefore, the authorization server implementation should generate a response with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client or developer since "500 Internal Server Error" is not required by the specification. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client or developer was wrong. The authorization server implementation should generate a response with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the registration access token used by the client configuration request (RFC 7592) is invalid, or the client application which the token is tied to does not exist any longer or is invalid. The HTTP status of the response returned to the client application must be "401 Unauthorized" and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the endpoint implementation should generate and return to the client application. ``` HTTP/1.1 401 Unauthorized Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` NOTE: The `UNAUTHORIZED` value was added in October, 2021. See the description of `Service.unauthorizedOnClientConfigSupported` for details. ## DELETED When the value of `action` is `DELETED`, it means that the request from the client or developer is valid. The authorization server implementation should generate a response to the client or developer with "204 No Content". --- The following illustrates the response which the authorization server implementation should generate and return to the client or developer. ``` HTTP/1.1 204 No Content Cache-Control: no-store Pragma: no-cache ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/client_registration_request' - type: object required: - clientId - token example: clientId: '26837717140341' token: qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_registration_response' example: resultCode: A216001 resultMessage: '[A216001] The client has been deleted.' action: DELETED '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_registration_delete_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/client/registration/delete \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "clientId": "26837717140341", "token": "qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA"}' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); ClientRegistrationRequest req = new ClientRegistrationRequest(); req.setClientId("26837717140341"); req.setToken("qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA"); api.dynamicClientDelete(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = new ClientRegistrationRequest() req.clientId = '26837717140341' req.token = 'qs4Tu5TV7qqDYT93bFs6ISyhTByMF9o-54GY4JU5vTA' api.DynamicClientDelete(req) tags: - Dynamic Client Registration /api/{serviceId}/backchannel/authentication: post: summary: Process Backchannel Authentication Request description: | This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further. x-mint: metadata: description: "This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further." content: | This API is supposed to be called from within the implementation of the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) of the service. The endpoint implementation must extract the request parameters from the backchannel authentication request from the client application and pass them as the value of parameters request parameter for Authlete's `/backchannel/authentication` API. 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. The following code snippet is an example in JAX-RS showing how to extract request parameters from the backchannel authentication request. ```java @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post(String parameters) { // 'parameters' is the entity body of the backchannel authentication request. ...... } ``` The endpoint implementation does not have to parse the request parameters from the client application because Authlete's `/backchannel/authentication` API does it. The response from `/backchannel/authentication` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. The authorization server implementation should generate a response to the client application with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel authentication request failed. Note that client authentication is always required at the backchannel authentication endpoint. This implies that public clients are not allowed to use the backchannel authentication endpoint. The authorization server implementation should generate a response to the client application with "401 Unauthorized" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: (challenge) Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## USER_IDENTIFICATION When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication request from the client application is valid. The authorization server implementation has to follow the steps below. **[1] END-USER IDENTIFICATION** The first step is to determine the subject (= unique identifier) of the end-user from whom the client application wants to get authorization. According to the CIBA specification, a backchannel authentication request contains one (and only one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint by which the authorization server identifies the subject of an end-user. The authorization server implementation can know which hint is included in the backchannel authentication request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`, it means that the backchannel authentication request contains the `login_hint` request parameter as a hint. The value of the `hint` parameter is the value of the hint. For example, when the value of the `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint` request parameter. It is up to the authorization server implementation how to determine the subject of the end-user from the hint. Only when the `id_token_hint` request parameter is used, authorization server implementation can use the sub response parameter, which holds the value of the sub claim in the `id_token_hint` request parameter. **[2] END-USER IDENTIFICATION ERROR** There are some cases where the authorization server implementation encounters an error during the user identification process. In any error case, the service implementation has to return an HTTP response with the error response parameter to the client application. The following is an example of such error responses. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "error":"unknown_user_id" } ``` Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON) of an error response. However, because it is easy to build an error response manually, you may choose not to call the API. One good thing in using the API is that the API call can trigger deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API. If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in the database until it is cleaned up by the batch program after the ticket expires. Possible error cases that the authorization server implementation itself has to handle are as follows. Other error cases have already been covered by `/backchannel/authentication` API. - `expired_login_hint_token` The authorization server implementation detected that the hint presented by the `login_hint_token` request parameter has expired. Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation of `login_hint_token` is left to each authorization server implementation. - `unknown_user_id` The authorization server implementation could not determine the subject of the end-user by the presented hint. - `unauthorized_client` The authorization server implementation has custom rules to reject backchannel authentication requests from some particular clients and found that the client which has made the backchannel authentication request is one of the particular clients. Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in cases where the client does not exist or client authentication has failed. Therefore, the authorization server implementation will never have to use the error code `unauthorized_client` unless the server has intentionally implemented custom rules to reject backchannel authentication requests based on clients. - `missing_user_code` The authorization server implementation has custom rules to require that a backchannel authentication request include a user code for some particular users and found that the user identified by the hint is one of the particular users. Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when both the `backchannel_user_code_parameter_supported` metadata of the server and the `backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication request does not include the user_code request parameter. In this case, `/backchannel/authentication` API returns action=BAD_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore, the authorization server implementation will never have to use the error code `missing_user_code` unless the server has intentionally implemented custom rules to require a user code based on users even in the case where the `backchannel_user_code_parameter` metadata of the client which has made the backchannel authentication request is `false`. - `invalid_user_code` The authorization server implementation detected that the presented user code is invalid. Note that the format of user_code is not described in the CIBA Core spec at all and so there is no consensus on how to judge whether a user code is valid or not. It is up to each authorization server implementation how to handle user codes. - `invalid_binding_message` The authorization server implementation detected that the presented binding message is invalid. Note that the format of binding_message is not described in the CIBA Core spec at all and so there is no consensus on how to judge whether a binding message is valid or not. It is up to each authorization server implementation how to handle binding messages. - `invalid_target` The authorization server implementation rejects the requested target resources. The error code invalid_target is from "Resource Indicators for OAuth 2.0". The specification defines the resource request parameter. By using the parameter, client applications can request target resources that should be bound to the access token being issued. If the authorization server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`. - `access_denined` The authorization server implementation has custom rules to reject backchannel authentication requests without asking the end-user and respond to the client as if the end-user had rejected the request in some particular cases and found that the backchannel authentication request is one of the particular cases. The authorization server implementation will never have to use the error code `access_denied` at this timing unless the server has intentionally implemented custom rules to reject backchannel authentication requests without asking the end-user and respond to the client as if the end-user had rejected the request. **[3] AUTH_REQ_ID ISSUE** If the authorization server implementation has successfully determined the subject of the end-user, the next action is to return an HTTP response to the client application which contains `auth_req_id`. Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`, so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response to the client application using the content of the API response, and (4) return the response to the client application. See the description of `/backchannel/authentication/issue` API for details. **[4] END-USER AUTHENTICATION AND AUTHORIZATION** After sending a JSON containing `auth_req_id` back to the client application, the service implementation starts to communicate with an authentication device of the end-user. It is assumed that end-user authentication is performed on the authentication device and the end-user confirms the content of the backchannel authentication request and grants authorization to the client application if everything is okay. The authorization server implementation must be able to receive the result of the end-user authentication and authorization from the authentication device. How to communicate with an authentication device and achieve end-user authentication and authorization is up to each authorization server implementation, but the following request parameters of the backchannel authentication request should be taken into consideration in any implementation. - `acr_values` A backchannel authentication request may contain an array of ACRs (Authentication Context Class References) in preference order. If multiple authentication devices are registered for the end-user, the authorization server implementation should take the ACRs into consideration when selecting the best authentication device. - `scope` A backchannel authentication request always contains a list of scopes. At least, `openid` is included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`). It would be better to show the requested scopes to the end-user on the authentication device or somewhere appropriate. If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0". That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded result. - `binding_message` A backchannel authentication request may contain a binding message. It is a human readable identifier or message intended to be displayed on both the consumption device (client application) and the authentication device. - `user_code` A backchannel authentication request may contain a user code. It is a secret code, such as password or pin, known only to the end-user but verifiable by the authorization server. The user code should be used to authorize sending a request to the authentication device. **[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION** After receiving the result of end-user authentication and authorization, the authorization server implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete the result and pass necessary data so that Authlete can generate an ID token, an access token and optionally a refresh token. See the description of the API for details. **[6] CLIENT NOTIFICATION** When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation must send a notification to the pre-registered notification endpoint of the client after the end-user authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete` API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details. **[7] TOKEN REQUEST** When the backchannel token delivery mode is either `ping` or `poll`, the client application will make a token request to the token endpoint to get an ID token, an access token and optionally a refresh token. A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba` as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the grant type automatically and behaves properly, so the existing token endpoint implementation does not have to be changed to support CIBA. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_request' example: parameters: login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code clientId: '26862190133482' clientSecret: 8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_response' example: resultCode: A179001 resultMessage: '[A179001] The backchannel authentication request was processed successfully.' action: USER_IDENTIFICATION clientId: 26862190133482 clientIdAliasUsed: false clientName: My CIBA Client clientNotificationToken: my-client-notification-token deliveryMode: POLL hint: john hintType: LOGIN_HINT requestedExpiry: 0 scopes: - defaultEntry: false name: openid serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value ticket: Y1qeCf0A-JUz6caceaBfd2AaBYNZ-X-WGTP5Qv47cQI userCode: my-user-code userCodeRequired: false '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters": "login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code", "clientId": "26862190133482", "clientSecret":"8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationRequest req = new BackchannelAuthenticationRequest(); req.setParameters(...); req.setClientId("26862190133482"); req.setClientSecret("8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A"); api.backchannelAuthentication(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationRequest() req.parameters = ... req.clientId = '26862190133482' req.clientSecret = '8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A' api.backchannelAuthentication(req) tags: - CIBA /api/{serviceId}/backchannel/authentication/issue: post: summary: Issue Backchannel Authentication Response description: | This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) x-mint: metadata: description: "This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)" content: | This API is supposed to be called from within the implementation of the backchannel authentication endpoint of the service in order to generate a successful response to the client application. The description of the `/backchannel/authentication` API describes the timing when this API should be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`. The response from `/backchannel/authentication/issue` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next `action` that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ```java @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post(String parameters) { // 'parameters' is the entity body of the backchannel authentication request. ...... } ``` The endpoint implementation does not have to parse the request parameters from the client application because Authlete's `/backchannel/authentication` API does it. The response from `/backchannel/authentication` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## INVALID_TICKET When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call was invalid. For example, it does not exist or has expired. From a viewpoint of the client application, this is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with "500 Internal Server Error" and `application/json`. You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`. ## OK When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response that is returned to the client from the backchannel authentication endpoint. `responseContent` contains the JSON. The following illustrates the response which the authorization server implementation should generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_issue_request' example: ticket: NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_issue_request' responses: '200': description: Backchannel authentication issued successfully content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_issue_response' example: resultCode: A183001 resultMessage: '[A183001] An auth_req_id was issued successfully.' action: OK authReqId: _mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE expiresIn: 3600 interval: 0 responseContent: '{\"auth_req_id\":\"_mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE\",\"interval\":0,\"expires_in\":3600}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_issue_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/issue \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationIssueRequest req = new BackchannelAuthenticationIssueRequest(); req.setTicket("NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q"); api.backchannelAuthenticationIssue(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationIssueRequest() req.ticket = 'NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q' api.backchannelAuthenticationIssue(req) tags: - CIBA /api/{serviceId}/backchannel/authentication/fail: post: summary: Fail Backchannel Authentication Request description: | The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint). x-mint: metadata: description: "The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)." content: | This API is supposed to be called from within the implementation of the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) of the service in order to generate an error response to the client application. The response from `/backchannel/authentication/fails` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that (1) the `reason` request parameter of the API call was `SERVER_ERROR`, (2) an error occurred on Authlete side, or (3) the request parameters of the API call were wrong. In this case, the authorization server implementation should return a "500 Internal Server Error" response to the client application. However, in most cases, commercial implementations prefer to use other HTTP status code than 5xx. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, the authorization server implementation should return a "400 Bad Request" response to the client application. ## FORBIDDEN When the value of `action` is `FORBIDDEN`, it means that the `reason` request parameter of the API call was `ACCESS_DENIED`. In this case, the backchannel authentication endpoint of the authorization server implementation should return a "403 Forbidden" response to the client application. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_fail_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_fail_response' example: resultCode: A185001 resultMessage: '[A185001] Successfully generated an error response for the backchannel authentication request.' action: FORBIDDEN responseContent: '{\"error\":\"access_denied\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_fail_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/fail \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0", "reason": "ACCESS_DENIED" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationFailRequest req = new BackchannelAuthenticationFailRequest(); req.setTicket("holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0"); req.setReason(BackchannelAuthenticationFailRequest.Reason.ACCESS_DENIED); api.backchannelAuthenticationFail(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationFailRequest() req.ticket = 'holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0' req.reason = BackchannelAuthenticationFailReason.ACCESS_DENIED api.backchannelAuthenticationFail(req) tags: - CIBA /api/{serviceId}/backchannel/authentication/complete: post: summary: Complete Backchannel Authentication description: | This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device. x-mint: metadata: description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device." content: | After the implementation of the backchannel authentication endpoint returns JSON containing an `auth_req_id` to the client, the authorization server starts a background process that communicates with the authentication device of the end-user. On the authentication device, end-user authentication is performed and the end-user is asked whether they give authorization to the client or not. The authorization server will receive the result of end-user authentication and authorization from the authentication device. After the authorization server receives the result from the authentication device, or even in the case where the server gave up receiving a response from the authentication device for some reasons, the server should call the `/backchannel/authentication/complete` API to tell Authlete the result. When the end-user was authenticated and authorization was granted to the client by the end-user, the authorization server should call the API with `result=AUTHORIZED`. In this successful case, the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate tokens later. When the authorization server received the decision of the end-user from the authentication device and it indicates that the end-user has rejected to give authorization to the client, the authorization server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode is `push`, the API will generate an error response that contains the error response parameter and optionally the `error_description` and error_uri response parameters (if the `errorDescription` and `errorUri` request parameters have been given). On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate an error response later. In any token delivery mode, the value of the error parameter will become `access_denied`. When the authorization server could not get the result of end-user authentication and authorization from the authentication device for some reasons, the authorization server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` parameter. The response from `/backchannel/authentication/complete` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization server to Authlete was wrong, or (2) that an error occurred on Authlete side. When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`) is retrieved from the database successfully. If an error is detected after the record of the ticket is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`. When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether it is before or after the record of the ticket is retrieved from the database. ## NO_ACTION When the value of `action` is `NO_ACTION`, it means that the authorization server does not have to take any immediate action. `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client will receive the final result at the token endpoint. ## NOTIFICATION When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a notification to the client notification endpoint. According to the CIBA Core specification, the notification is an HTTP POST request whose request body is JSON and whose `Authorization` header contains the client notification token, which was included in the backchannel authentication request as the value of the `client_notification_token` request parameter, as a bearer token. When the backchannel token delivery mode is `ping`, the request body of the notification is JSON which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`, the request body will additionally contain an access token, an ID token and other properties. Note that when the backchannel token delivery mode is `poll`, a notification does not have to be sent to the client notification endpoint. In error cases, in the ping mode, however, the content of a notification is not different from the content in successful cases. That is, the notification contains the `auth_req_id` property only. The client will know the error when it accesses the token endpoint. On the other hand, in the `push` mode, in error cases, the content of a notification will include the `error` property instead of an access token and an ID token. The client will know the error by detecting that error is included in the notification. In any case, the value of `responseContent` is JSON which can be used as the request body of the notification. The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint` parameter. Likewise, the client notification token that the notification should include as a bearer token is the `clientNotificationToken` parameter. With these methods, the notification can be built like the following. ``` POST {clientNotificationEndpoint} HTTP/1.1 HOST: {The host of clientNotificationEndpoint} Authorization: Bearer {notificationToken} Content-Type: application/json {responseContent} ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_complete_request' example: ticket: NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q result: AUTHORIZED subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_complete_request' responses: '200': description: Backchannel authentication completed successfully content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_complete_response' example: resultCode: A198001 resultMessage: '[A198001] Successfully updated the database so that the token endpoint can generate tokens (mode = poll, result = AUTHORIZED).' accessTokenDuration: 0 action: NO_ACTION authReqId: _mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE clientId: 26862190133482 clientIdAliasUsed: false clientName: My CIBA Client deliveryMode: POLL idTokenDuration: 0 refreshTokenDuration: 0 serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_complete_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/complete \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q", "result": "AUTHORIZED", "subject": "john" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationCompleteRequest req = new BackchannelAuthenticationCompleteRequest(); req.setTicket("NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q"); req.setResult(BackchannelAuthenticationCompleteRequest.Result.AUTHORIZED); req.setSubject("john"); api.backchannelAuthenticationComplete(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationCompleteRequest() req.ticket = 'NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q' req.result = BackchannelAuthenticationCompleteResult.AUTHORIZED req.subject = 'john' api.backchannelAuthenticationComplete(req) tags: - CIBA /api/{serviceId}/device/authorization: post: summary: Process Device Authorization Request description: | This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further. x-mint: metadata: description: "This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) and returns necessary data for the authorization server implementation to process the device authorization request further." content: | This API is supposed to be called from the within the implementation of the device authorization endpoint of the service. The service implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes t he error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is wrong. The authorization server implementation should generate a response to the client application with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization request failed. The authorization server implementation should generate a response to the client application with "401 Unauthorized" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: (challenge) Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## OK When the value of `action` is `OK`, it means that the device authorization request from the client application is valid. The authorization server implementation should generate a response to the client application with "200 OK" and `application/json`. The `responseContent` is a JSON string which can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client application. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_authorization_request' example: parameters: client_id=26888344961664&scope=history.read clientId: '26888344961664' clientSecret: SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_authorization_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/device_authorization_response' example: resultCode: A220001 resultMessage: '[A220001] The device authorization request was processed successfully.' action: OK clientId: 26888344961664 clientIdAliasUsed: false clientName: My Device Flow Client deviceCode: p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I expiresIn: 3600 interval: 0 responseContent: '{"user_code":"XWWKPBWVXQ","device_code":"p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I","verification_uri_complete":"https://my-service.com/df/verification?XWWKPBWVXQ","verification_uri":"https://my-service.com/df/verification","expires_in":3600}' scopes: - defaultEntry: false name: history.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value userCode: XWWKPBWVXQ verificationUri: https://my-service.com/df/verification verificationUriComplete: https://my-service.com/df/verification?XWWKPBWVXQ links: device_verify: $ref: '#/components/links/device_verification' device_poll_token: $ref: '#/components/links/device_complete' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_authorization_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/device/authorization \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "parameters": "client_id=26888344961664&scope=history.read", "clientId": "26888344961664", "clientSecret":"SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceAuthorizationRequest req = new DeviceAuthorizationRequest(); req.setParameters(...); req.setClientId("26888344961664"); req.setClientSecret("SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog"); api.deviceAuthorization(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = DeviceAuthorizationRequest() req.parameters = ... req.clientId = '26888344961664' req.clientSecret = 'SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog' api.deviceAuthorization(req) tags: - Device Flow /api/{serviceId}/device/verification: post: summary: Process Device Verification Request description: | The API returns information associated with a user code. x-mint: metadata: description: "The API returns information associated with a user code." content: | After receiving a response from the device authorization endpoint of the authorization server, the client application shows the end-user the user code and the verification URI which are included in the device authorization response. Then, the end-user will access the verification URI using a web browser on another device (typically, a smart phone). In normal implementations, the verification endpoint will return an HTML page with an input form where the end-user inputs a user code. The authorization server will receive a user code from the form. After receiving a user code, the authorization server should call Authlete's `/device/verification` API with the user code. And then, the authorization server implementation should retrieve the value of `action` parameter from the API response and take the following steps according to the value. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The authorization server implementation should tell the end-user that something wrong happened and urge her to re-initiate a device flow. ## NOT_EXIST When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization server implementation should tell the end-user that the user code is invalid and urge her to retry to input a valid user code. ## EXPIRED When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization server implementation should tell the end-user that the user code has expired and urge her to re-initiate a device flow. ## VALID When the value of `action` is `VALID`, it means that the user code exists, has not expired, and belongs to the service. The authorization server implementation should interact with the end-user to ask whether she approves or rejects the authorization request from the device. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_verification_request' example: userCode: XWWKPBWVXQ application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_verification_request' responses: '200': description: Device verification completed successfully content: application/json: schema: $ref: '#/components/schemas/device_verification_response' example: resultCode: A224001 resultMessage: '[A224001] The user code is valid.' action: VALID clientId: 26888344961664 clientIdAliasUsed: false clientName: My Device Flow Client expiresAt: 1642001978000 scopes: - defaultEntry: false name: history.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_verification_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/device/verification \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "userCode": "XWWKPBWVXQ" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceVerificationRequest req = new DeviceVerificationRequest(); req.setUserCode("XWWKPBWVXQ"); api.deviceVerification(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = DeviceVerificationRequest() req.setUserCode('XWWKPBWVXQ') api.deviceVerification(req) tags: - Device Flow /api/{serviceId}/device/complete: post: summary: Complete Device Authorization description: | This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request. x-mint: metadata: description: "This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request." content: | In the device flow, an end-user accesses the verification endpoint of the authorization server where she interacts with the verification endpoint and inputs a user code. The verification endpoint checks if the user code is valid and then asks the end-user whether she approves or rejects the authorization request which the user code represents. After the authorization server receives the decision of the end-user, it should call Authlete's `/device/complete` API to tell Authlete the decision. When the end-user was authenticated and authorization was granted to the client by the end-user, the authorization server should call the API with `result=AUTHORIZED`. In this successful case, the subject request parameter is mandatory. The API will update the database record so that `/auth/token` API can generate an access token later. If the `scope` parameter of the device authorization request included the openid scope, an ID token is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API call to `/device/complete` affect the ID token. When the authorization server receives the decision of the end-user and it indicates that she has rejected to give authorization to the client, the authorization server should call the API with `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token` API can generate an error response later. If `errorDescription` and `errorUri` request parameters are given to the `/device/complete` API, they will be used as the values of `error_description` and `error_uri` response parameters in the error response from the token endpoint. When the authorization server could not get decision from the end-user for some reasons, the authorization server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` response parameter instead of `access_denied`. After receiving a response from the `/device/complete` API, the implementation of the authorization server should retrieve the value of `action` from the response and take the following steps according to the value. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The authorization server implementation should tell the end-user that something wrong happened and urge her to re-initiate a device flow. ## USER_CODE_NOT_EXIST When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API call does not exist. The authorization server implementation should tell the end-user that the user code has been invalidated and urge her to re-initiate a device flow. ## USER_CODE_EXPIRED When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API call has expired. The authorization server implementation should tell the end-user that the user code has expired and urge her to re-initiate a device flow. ## INVALID_REQUEST When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably, the authorization server implementation has some bugs. ## SUCCESS When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully. The authorization server should return a successful response to the web browser the end-user is using. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_complete_request' example: userCode: XWWKPBWVXQ result: AUTHORIZED subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_complete_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/device_complete_response' example: resultCode: A241001 resultMessage: '[A241001] The API call was processed successfully.' action: SUCCESS '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_complete_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/device/complete \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "userCode": "XWWKPBWVXQ", "result": "AUTHORIZED", "subject": "john" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceCompleteRequest req = new DeviceCompleteRequest(); req.setUserCode("XWWKPBWVXQ"); req.setResult(DeviceCompleteRequest.Result.AUTHORIZED); req.setSubject("john"); api.deviceComplete(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = DeviceCompleteRequest() req.setUserCode('XWWKPBWVXQ') req.setResult(DeviceCompleteResult.AUTHORIZED) req.setSubject('john') api.deviceComplete(req) tags: - Device Flow /api/{serviceId}/auth/token/get/list: get: summary: List Issued Tokens description: | Get the list of access tokens that are associated with the service. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: query name: clientIdentifier schema: type: string required: false description: | Client Identifier (client ID or client ID alias). - in: query name: subject schema: type: string required: false description: | Unique user ID. - in: query name: start schema: type: integer format: int32 required: false description: Start index of search results (inclusive). The default value is 0. - in: query name: end schema: type: integer format: int32 required: false description: | End index of search results (exclusive). The default value is 5. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/token_get_list_response' example: accessTokens: - accessTokenExpiresAt: 1642048149000 accessTokenHash: tC5hpjGylLiiw-vsd5_tqVHtYSUHblAGimEJ-5xqAco clientId: 26888344961664 createdAt: 1642044549000 grantType: AUTHORIZATION_CODE lastRefreshedAt: 0 refreshTokenExpiresAt: 1642048149000 refreshTokenHash: jv4B_7_kpY-Rez_E7bYIxGYnZk43w18uigkaeUe6tc4 scopes: - history.read subject: john - accessTokenExpiresAt: 1642051604000 accessTokenHash: Bk1QneTxkoLKw_RRB8ToVL25Plt075RvPK68N9cWWtg clientId: 26888344961664 createdAt: 1642048004000 grantType: AUTHORIZATION_CODE lastRefreshedAt: 0 refreshTokenExpiresAt: 1642051604000 refreshTokenHash: YHmwk4xETvoIJ_maWCpJDlpvmcFLkxmaaSS-v9KPng4 scopes: - history.read - openid - timeline.read subject: john - accessTokenExpiresAt: 1642052094000 accessTokenHash: UUatYXjkqYFbRQlnItjq03DtUYA2MRRtuL88GCbQpbw clientId: 26888344961664 createdAt: 1642048494000 grantType: AUTHORIZATION_CODE lastRefreshedAt: 0 refreshTokenExpiresAt: 1642052094000 refreshTokenHash: wjc-IXoScxDiVyBmRrB92I-B0zMXSSKw_qwP_WK1lFM scopes: - history.read subject: john client: clientId: 26888344961664 clientIdAliasEnabled: false clientName: My Device Flow Client clientType: CONFIDENTIAL number: 6260 end: 3 start: 0 subject: john totalCount: 3 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_get_list_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/auth/token/get/list/?clientIdentifier=26888344961664\&subject=john\&start=0\&end=3 \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); String clientIdentifier = "26888344961664"; String subject = "john"; int start = 0; int end = 3; api.getTokenList(clientIdentifier, subject, start, end); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) clientIdentifier = '26888344961664' subject = 'john' start = 0 end = 3 api.getTokenList(clientIdentifier, subject, start, end) tags: - Token Operations /api/{serviceId}/auth/token/create: post: summary: Create Access Token description: | Create an access token. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_create_request' example: grantType: AUTHORIZATION_CODE clientId: 26888344961664 subject: john scopes: - history.read - timeline.read application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_create_request' responses: '200': description: Token created successfully content: application/json: schema: $ref: '#/components/schemas/token_create_response' example: resultCode: A109001 resultMessage: '[A109001] An access token was created successfully: authorization_code, client = 26888344961664' accessToken: Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q action: OK clientId: 26888344961664 expiresAt: 1642048148973 expiresIn: 3600 grantType: AUTHORIZATION_CODE refreshToken: 9beh15GWkGLseBBO1tPobnsGpKLHV3mTkm0EWnNBa4g scopes: - history.read - timeline.read subject: john tokenType: Bearer '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_create_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/create \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "grantType": "AUTHORIZATION_CODE", "clientId": 26888344961664, "subject": "john", "scopes": [ "history.read", "timeline.read" ] }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenCreateRequest req = new TokenCreateRequest(); req.setGrantType(GrantType.AUTHORIZATION_CODE) req.setClientId(26888344961664) req.setSubject("john") req.setScopes({ "history.read", "timeline.read" }); api.tokenCreate(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenCreateRequest() req.grantType = GrantType.AUTHORIZATION_CODE req.clientId = 26888344961664 req.subject = 'john' req.scopes = [ 'history.read', 'timeline.read' ] api.tokenCreate(req) tags: - Token Operations /api/{serviceId}/auth/token/update: post: summary: Update Access Token description: | Update an access token. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_update_request' example: accessToken: Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q scopes: - history.read application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_update_request' responses: '200': description: Token updated successfully content: application/json: schema: $ref: '#/components/schemas/token_update_response' example: resultCode: A135001 resultMessage: '[A135001] Updated the access token successfully.' accessToken: Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q accessTokenExpiresAt: 1642048149000 action: OK scopes: - history.read tokenType: Bearer links: token_issue: $ref: '#/components/links/token_issue' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_update_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/update \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "accessToken": "Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q", "scopes": [ "history.read" ] }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenUpdateRequest req = new TokenUpdateRequest(); req.setAccessToken("JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs"); req.setScopes({ "history.read" }); api.tokenUpdate(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenUpdateRequest() req.accessToken = 'JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs' req.scopes = [ 'history.read' ] api.tokenUpdate(req) tags: - Token Operations /api/{serviceId}/auth/token/delete/{accessTokenIdentifier}: delete: summary: Delete Access Token description: | Delete an access token. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: accessTokenIdentifier schema: type: string required: true description: | The identifier of an existing access token. The identifier is the value of the access token or the value of the hash of the access token. responses: '204': description: | The access token was successfully deleted. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_delete_api x-code-samples: - lang: shell label: curl source: | curl -v -X DELETE https://us.authlete.com/api/21653835348762/auth/token/delete/Bk1QneTxkoLKw_RRB8ToVL25Plt075RvPK68N9cWWtg \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); String accessTokenIdentifier = "Bk1QneTxkoLKw_RRB8ToVL25Plt075RvPK68N9cWWtg"; api.tokenDelete(accessToken); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) accessTokenIdentifier = 'Bk1QneTxkoLKw_RRB8ToVL25Plt075RvPK68N9cWWtg' api.tokenDelete(accessToken) tags: - Token Operations /api/{serviceId}/auth/token/revoke: post: summary: Revoke Access Token description: | Revoke an access token. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_revoke_request' example: accessTokenIdentifier: Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_revoke_request' responses: '200': description: Token revoked successfully content: application/json: schema: $ref: '#/components/schemas/token_revoke_response' example: resultCode: A312001 resultMessage: Revoked 1 access token(s). count: 1 '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' operationId: auth_token_revoke_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/revoke \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "accessTokenIdentifier": "Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenRevokeRequest req = new TokenRevokeRequest(); req.setAccessTokenIdentifier("Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q"); api.tokenRevoke(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = TokenRevokeRequest() req.access_token_identifier = 'Z5a40U6dWvw2gMoCOAFbZcM85q4HC0Z--0YKD9-Nf6Q' api.token_revoke(req) tags: - Token Operations /api/{serviceId}/jose/verify: post: summary: Verify JOSE description: | This API verifies a JOSE object. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/jose_verify_request' example: jose: eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtwyxBgMXQqEPD5q5k9FaEWNk37K8uAtSwrA clockSkew: 100 signedByClient: true clientIdentifier: '57297408867' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/jose_verify_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/jose_verify_response' example: resultCode: A160001 resultMessage: '[A160001] The JOSE is valid.' signatureValid: true valid: true links: token_exchange: $ref: '#/components/links/token_exchange' token_introspect: $ref: '#/components/links/token_introspect' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: jose_verify_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/jose/verify \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d jose=eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtwyxBgMXQqEPD5q5k9FaEWNk37K8uAtSwrA \ -d clockSkew=100 \ -d signedByClient=true \ -d clientIdentifier=57297408867 - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); JoseVerifyRequest req = new JoseVerifyRequest(); req.setJose("eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtw"); req.setClockSkew(100); req.setSinedByClient(true); req.setClientIdentifier("57297408867"); api.verifyJose(request); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = JoseVerifyRequest() req.jose = 'eyJhbGciOiJFUzI1NiJ9.eyJleHAiOjE1NTk4MTE3NTAsImlzcyI6IjU3Mjk3NDA4ODY3In0K.csmdholMVcmjqHe59YWgLGNvm7I5Whp4phQCoGxyrlRGMnTgsfxtw' req.clockSkew = 100 req.sinedByClient = True req.clientIdentifier = '57297408867' api.verifyJose(req) tags: - Jose Object /api/{serviceId}/federation/configuration: post: summary: Process Entity Configuration Request description: | This API gathers the federation configuration about a service. The authorization server implementation should retrieve the value of the `action` response parameter from the API response and take the following steps according to the value. x-mint: metadata: description: "This API gathers the federation configuration about a service. The authorization server implementation should retrieve the value of the `action` response parameter from the API response and take the following steps according to the value." content: | ### `OK` When the value of the `action` response parameter is `OK`, it means that Authlete could prepare an entity configuration successfully. In this case, the implementation of the entity configuration endpoint of the authorization server should return an HTTP response to the client application with the HTTP status code "`200 OK`" and the content type "`application/entity-statement+jwt`". The message body (= an entity configuration in the JWT format) of the response has been prepared by Authlete's `/federation/configuration` API and it is available as the `responseContent` response parameter. The implementation of the entity configuration endpoint can construct an HTTP response by doing like below. ``` 200 OK Content-Type: application/entity-statement+jwt (Other HTTP headers) (the value of the responseContent response parameter) ``` ### `NOT_FOUND` When the value of the `action` response parameter is `NOT_FOUND`, it means that the service configuration has not enabled the feature of [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html) and so the client application should have not access the entity configuration endpoint. In this case, the implementation of the entity configuration endpoint of the authorization server should return an HTTP response to the client application with the HTTP status code "`404 Not Found`" and the content type "`application/json`". The message body (= error information in the JSON format) of the response has been prepared by Authlete's `/federation/configuration` API and it is available as the `responseContent` response parameter. The implementation of the entity configuration endpoint can construct an HTTP response by doing like below. ``` 404 Not Found Content-Type: application/json (Other HTTP headers) (the value of the responseContent response parameter) ``` ### `INTERNAL_SERVER_ERROR` could prepare an entity configuration successfully. In this case, the implementation of the entity configuration endpoint of the authorization server should return an HTTP response to the client application with the HTTP status code "`200 OK`" and the content type "`application/entity-statement+jwt`". The message body (= an entity configuration in the JWT format) of the response has been prepared by Authlete's `/federation/configuration` API and it is available as the `responseContent` response parameter. The implementation of the entity configuration endpoint can construct an HTTP response by doing like below. ``` 200 OK Content-Type: application/entity-statement+jwt (Other HTTP headers) (the value of the responseContent response parameter) ``` parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: content: application/json: schema: type: object responses: '200': description: Federation configuration retrieved successfully content: application/json: schema: $ref: '#/components/schemas/federation_configuration_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: federation_configuration_api x-code-samples: - lang: shell label: curl source: | curl -v https://us.authlete.com/api/21653835348762/federation/configuration \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); api.getFederationConfiguration(); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) api.getFederationConfiguration(True) tags: - Federation Endpoint /api/{serviceId}/federation/registration: post: summary: Process Federation Registration Request description: | The Authlete API is for implementations of the **federation registration endpoint** that accepts "explicit client registration". Its details are defined in [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html). The endpoint accepts `POST` requests whose `Content-Type` is either of the following. 1. `application/entity-statement+jwt`- `application/trust-chain+json` When the `Content-Type` of a request is `application/entity-statement+jwt`, the content of the request is the entity configuration of a relying party that is to be registered. In this case, the implementation of the federation registration endpoint should call Authlete's `/federation/registration` API with the entity configuration set to the `entityConfiguration` request parameter. On the other hand, when the `Content-Type` of a request is `application/trust-chain+json`, the content of the request is a JSON array that contains entity statements in JWT format. The sequence of the entity statements composes the trust chain of a relying party that is to be registered. In this case, the implementation of the federation registration endpoint should call Authlete's `/federation/registration` API with the trust chain set to the `trustChain` request parameter. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/federation_registration_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/federation_registration_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/federation_registration_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: federation_registration_api tags: - Federation Endpoint /api/info: get: security: [] summary: Get Server Metadata description: | get the server version and enabled features responses: '200': description: API information retrieved successfully content: application/json: schema: $ref: '#/components/schemas/info_response' example: version: 2.3.0 features: - ciba - dcr - deviceflow - fapi - openbanking - hsm - gm - tc - oidc_federation '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: info_api tags: - Utility Endpoints /api/{serviceId}/client/extension/requestable_scopes/get/{clientId}: get: summary: Get Requestable Scopes description: | Get the requestable scopes per client parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/client_extension_requestable_scopes_get_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_extension_requestables_scopes_get_api tags: - Client Management /api/{serviceId}/client/extension/requestable_scopes/update/{clientId}: post: summary: Update Requestable Scopes description: | Update requestable scopes of a client parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/client_extension_requestable_scopes_update_request' responses: '200': description: Requestable scopes updated successfully content: application/json: schema: $ref: '#/components/schemas/client_extension_requestable_scopes_update_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_extension_requestables_scopes_update_api_post tags: - Client Management put: summary: Update Requestable Scopes description: | Update requestable scopes of a client parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/client_extension_requestable_scopes_update_request' responses: '200': description: Requestable scopes updated successfully content: application/json: schema: $ref: '#/components/schemas/client_extension_requestable_scopes_update_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_extension_requestables_scopes_update_api tags: - Client Management /api/{serviceId}/client/extension/requestable_scopes/delete/{clientId}: delete: summary: Delete Requestable Scopes description: | Delete requestable scopes of a client parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: clientId schema: type: string required: true description: | A client ID. responses: '204': description: Requestable scopes was successfully deleted. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: client_extension_requestables_scopes_delete_api tags: - Client Management /api/{serviceId}/hsk/create: post: summary: Create Security Key x-badges: - color: primary-color label: 🏒 Dedicated Cloud Required parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/hsk_create_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/hsk_create_request' responses: '200': description: HSK created successfully content: application/json: schema: $ref: '#/components/schemas/hsk_create_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: hsk_create_api tags: - Hardware Security Key /api/{serviceId}/hsk/delete/{handle}: delete: summary: Delete Security Key x-badges: - color: primary-color label: 🏒 Dedicated Cloud Required parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: handle schema: type: string required: true responses: '204': description: HSK deleted successfully content: application/json: schema: $ref: '#/components/schemas/hsk_delete_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: hsk_delete_api tags: - Hardware Security Key /api/{serviceId}/hsk/get/{handle}: get: summary: Get Security Key x-badges: - color: primary-color label: 🏒 Dedicated Cloud Required parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string - in: path name: handle schema: type: string required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/hsk_get_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: hsk_get_api tags: - Hardware Security Key /api/{serviceId}/hsk/get/list: get: summary: List Security Keys x-badges: - color: primary-color label: 🏒 Dedicated Cloud Required parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string responses: '200': description: HSK list retrieved successfully content: application/json: schema: $ref: '#/components/schemas/hsk_get_list_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: hsk_get_list_api tags: - Hardware Security Key /api/misc/echo: get: summary: Echo description: | Echo test endpoint. Will return all path parameters in the request responses: '200': description: | Successfully echoed the request parameters operationId: misc_echo_api tags: - Utility Endpoints /api/{serviceId}/vci/metadata: post: summary: Get Verifiable Credential Issuer Metadata description: Get verifiable credential issuer metadata parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_metadata_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_metadata_request' responses: '200': description: VCI metadata retrieved successfully content: application/json: schema: $ref: '#/components/schemas/vci_metadata_response' links: vci_offer_create: $ref: '#/components/links/vci_offer_create' vci_vp_metadata: $ref: '#/components/links/vci_vp_metadata' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_metadata_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/jwtissuer: post: summary: Get JWT Issuer Information description: Get JWT issuer information for VCI parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_jwtissuer_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_jwtissuer_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_jwtissuer_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_jwtissuer_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/jwks: post: summary: Get JSON Web Key Set description: Get JSON Web Key Set for VCI parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_jwks_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_jwks_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_jwks_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_jwks_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/offer/create: post: summary: Create Credential Offer description: Create a verifiable credential offer parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_offer_create_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_offer_create_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_offer_create_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_offer_create_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/offer/info: post: summary: Get Credential Offer Information description: Get information about a verifiable credential offer parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_offer_info_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_offer_info_request' responses: '200': description: Credential offer info retrieved successfully content: application/json: schema: $ref: '#/components/schemas/vci_offer_info_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_offer_info_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/single/parse: post: summary: Parse Single Credential description: Parse a single verifiable credential parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_single_parse_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_single_parse_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_single_parse_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_single_parse_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/single/issue: post: summary: Issue Single Credential description: Issue a single verifiable credential parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_single_issue_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_single_issue_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_single_issue_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/batch/parse: post: summary: Parse Batch Credentials description: Parse multiple verifiable credentials in batch parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_batch_parse_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_batch_parse_request' responses: '200': description: Batch credential parsing completed successfully content: application/json: schema: $ref: '#/components/schemas/vci_batch_parse_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_batch_parse_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/batch/issue: post: summary: Issue Batch Credentials description: Issue multiple verifiable credentials in batch parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_batch_issue_request' responses: '200': description: Batch credential issuance completed successfully content: application/json: schema: $ref: '#/components/schemas/vci_batch_issue_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_batch_issue_api tags: - Verifiable Credential Issuer /api/lifecycle/healthcheck: get: summary: Health Check security: [] description: | Perform a health check of the server. parameters: - in: query name: extended description: | If `true`, perform extended health checks (e.g. database connectivity). required: false schema: type: boolean responses: '200': description: OK content: text/plain: schema: type: string example: OK '500': description: Internal Server Error content: text/plain: schema: type: string tags: - Lifecycle /api/{serviceId}/vci/deferred/parse: post: summary: Parse Deferred Credential description: Parse a deferred verifiable credential parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_deferred_parse_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/vci_deferred_parse_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_deferred_parse_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_deferred_parse_api tags: - Verifiable Credential Issuer /api/{serviceId}/vci/deferred/issue: post: summary: Issue Deferred Credential description: Issue a deferred verifiable credential parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/vci_deferred_issue_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/vci_deferred_issue_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: vci_deferred_issue_api tags: - Verifiable Credential Issuer /api/{serviceId}/auth/authorization/ticket/info: post: operationId: getAuthorizationTicketInfo summary: Get Ticket Information parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_info_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_ticket_info_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_info_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/ticket/update: post: operationId: updateAuthorizationTicket summary: Update Ticket Information parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_update_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_ticket_update_request' responses: '200': description: Authorization ticket updated successfully content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_update_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' tags: - Authorization Endpoint /api/{serviceId}/nativesso: post: summary: Native SSO Processing description: | This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value. x-mint: metadata: description: "This API should be called by the implementation of a token endpoint to generate the ID token and token response that comply with [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO) when Authlete’s `/auth/token` response indicates `action = NATIVE_SSO` (after you validate the session id and verify or generate the device secret as required by the flow). The token endpoint implementation should retrieve the value of `action` from the response and take the following steps according to the value." content: | ## OK When the action is `OK`, it indicates that the `/nativesso` API processing has successfully completed. In this case, the token endpoint implementation should return a successful response (`200 OK`) to the client. The value of the responseContent property in the `/nativesso` API response can be used directly as the message body of the token response. Therefore, the success response can be constructed as follows: ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store (Embed the value of responseContent here.) ``` ## INTERNAL_SERVER_ERROR When the action is `INTERNAL_SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. For example, an issue such as a database error might have occurred when retrieving the access token specified by the accessToken parameter from the database. In such cases, the token endpoint implementation should return an error response to the client. The simplest implementation would be to return a `500 Internal Server Error`. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store (Embed the value of responseContent here.) ``` However, in a production environment, it may be better to return a more abstract error (one that does not directly describe the nature of the issue), rather than a `500` error. ## CALLER_ERROR When the action is `CALLER_ERROR`, it indicates that the issue lies with the caller of the API (i.e., the implementation of the OpenID Provider). For example, this could be due to missing a required parameter such as accessToken. If `CALLER_ERROR` is returned, please review the implementation of your OpenID Provider. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string example: '715948317' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/native_sso_request' example: accessToken: _kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq refreshToken: kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw deviceSecret: my-ds claims: '{"given_name":"John","family_name":"Brown","email":"test@example.com"}' responses: '200': description: Native SSO processing completed successfully content: application/json: schema: $ref: '#/components/schemas/native_sso_response' example: resultCode: A501001 resultMessage: '[A501001] A Native SSO-compliant ID token and a token response were generated successfully.' action: OK responseContent: '{\"access_token\":\"_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"openid device_sso\",\"refresh_token\":\"kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw\",\"id_token\":\"eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ\",\"device_secret\":\"my-ds\"}' idToken: eyJraWQiOiItc1RSWDc5YnEyOEhyYkxBV0w2N3k4T1VJdXdrTms2ZFFkbzItSExZMkxvIiwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsInN1YiI6ImpvaG4iLCJhdWQiOlsibmF0aXZlX2FwcF8xIl0sImV4cCI6MTc1NjcxNzY3MywiaWF0IjoxNzU2NzE3MzczLCJkc19oYXNoIjoic0luWlNhY1luRkR1Y1dwckRqZmtYeENRZl9mWGhsVDY1ZDduS0VYNzc2OCIsInNpZCI6Im15LXNpZCIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJCcm93biIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSJ9.RASuwd4KYPe8b3vNNwIYJgoXzUadDFFHO1wYWD70Z3EsZd8qcxxkPmJKs3dRitvYTX8DDqf5zvAm1jlIeEuvRQ links: authz_process: $ref: '#/components/links/authz_process' token_exchange: $ref: '#/components/links/token_exchange' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: native_sso_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/nativesso \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "accessToken": "_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq", "refreshToken": "kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw", "deviceSecret": "my-ds", "claims": "{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); NativeSsoRequest req = new NativeSsoRequest(); req.setAccessToken("_kh1aygxZ5NKLYKCJRM8M_AYvDg2wCWoprQDjfO87ZWq"); req.setRefreshToken("kHUGSt_d3LSgiCQzH7wa5TpwIHWgjAZGw14zZV7hRqw"); req.setDeviceSecret("my-ds"); req.setClaims("{\"given_name\":\"John\",\"family_name\":\"Brown\",\"email\":\"test@example.com\"}") api.nativeSso(req); tags: - Native SSO /api/{serviceId}/nativesso/logout: post: summary: Native SSO Logout Processing description: | The `/nativesso/logout` API is supposed to be used to support the concept of "logout from all applications" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO. x-mint: metadata: description: "The `/nativesso/logout` API is supposed to be used to support the concept of \"logout from all applications\" in the context of [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) (Native SSO). This is accomplished by deleting access/refresh token records associated with the specified session ID. In Authlete's implementation, access/refresh token records can be associated with a session ID only through the mechanism introduced by Native SSO." content: | A response from the `/nativesso/logout` API contains `action` response parameter. The possible values are: ## OK When the action is `OK`, it indicates that the `/nativesso/logout` API call completed successfully. ## SERVER_ERROR When the action is `SERVER_ERROR`, it indicates that something has gone wrong on the Authlete side. ## CALLER_ERROR When the action is `CALLER_ERROR`, it indicates that the `/nativesso/logout` API call contained a problem. For example, the call may have been missing the required request parameter `sessionId`. parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/native_sso_logout_request' example: sessionId: my-sid responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/native_sso_logout_response' example: action: OK count: 2 resultCode: A503001 resultMessage: '[A503001] The /nativesso/logout API call successfully deleted 2 access/refresh token record(s).' links: authz_process: $ref: '#/components/links/authz_process' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: native_sso_logout_api x-code-samples: - lang: shell label: curl source: | curl -v -X POST https://us.authlete.com/api/21653835348762/nativesso/logout \ -H 'Content-Type:application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "sessionId": "my-sid" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); NativeSsoLogoutRequest req = new NativeSsoLogoutRequest(); req.setSessionId("my-sid"); api.nativeSsoLogout(req); tags: - Native SSO components: 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 ` 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. schemas: access_token: type: object properties: accessTokenHash: type: string description: The hash of the access token. accessTokenExpiresAt: type: integer format: int64 description: The timestamp at which the access token will expire. refreshTokenHash: type: string description: The hash of the refresh token. refreshTokenExpiresAt: type: integer format: int64 description: The timestamp at which the refresh token will expire. createdAt: type: integer format: int64 description: | The timestamp at which the access token was first created. lastRefreshedAt: type: integer format: int64 description: | The timestamp at which the access token was last refreshed using the refresh token. clientId: type: integer format: int64 description: | The ID of the client associated with the access token. subject: type: string description: | The subject (= unique user ID) associated with the access token. grantType: $ref: '#/components/schemas/grant_type' scopes: type: array items: type: string description: | The scopes associated with the access token. properties: type: array items: $ref: '#/components/schemas/property' description: | The properties associated with the access token. refreshTokenScopes: type: array items: type: string description: | The scopes associated with the refresh token. application_type: type: string description: | The application type. The value of this property affects the validation steps for a redirect URI. See the description about `redirectUris` property for more details. enum: - WEB - NATIVE authz_details: type: object description: | The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests". properties: elements: type: array items: $ref: '#/components/schemas/authorization_details_element' description: | Elements of this authorization details. authorization_details_element: type: object required: - type properties: type: type: string description: | The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. locations: type: array items: type: string description: | The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. actions: type: array items: type: string description: | The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. dataTypes: type: array items: type: string description: | From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. identifier: type: string description: | The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. privileges: type: array items: type: string description: | The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. otherFields: type: string description: | The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. claim_type: type: string enum: - NORMAL - AGGREGATED - DISTRIBUTED client_auth_method: 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 client_extension: type: object properties: requestableScopes: type: array items: type: string description: | The set of scopes that the client application is allowed to request. This paramter will be one of the following. x-mint: metadata: description: "The set of scopes that the client application is allowed to request. This paramter will be one of the following." content: | - `null` - an empty set - a set with at least one element When the value of this parameter is `null`, it means that the set of scopes that the client application is allowed to request is the set of the scopes that the service supports. When the value of this parameter is an empty set, it means that the client application is not allowed to request any scopes. When the value of this parameter is a set with at least one element, it means that the set is the set of scopes that the client application is allowed to request. requestableScopesEnabled: type: boolean description: | The flag to indicate whether "Requestable Scopes per Client" is enabled or not. If `true`, you can define the set of scopes which this client application can request. If `false`, this client application can request any scope which is supported by the authorization server. accessTokenDuration: type: integer format: int64 description: | The value of the duration of access tokens per client in seconds. In normal cases, the value of the service's `accessTokenDuration` property is used as the duration of access tokens issued by the service. However, if this `accessTokenDuration` property holds a non-zero positive number and its value is less than the duration configured by the service, the value is used as the duration of access tokens issued to the client application. Note that the duration of access tokens can be controlled by the scope attribute `access_token.duration`, too. Authlete chooses the minimum value among the candidates. refreshTokenDuration: type: integer format: int64 description: | The value of the duration of refresh tokens per client in seconds. In normal cases, the value of the service's `refreshTokenDuration` property is used as the duration of refresh tokens issued by the service. However, if this `refreshTokenDuration` property holds a non-zero positive number and its value is less than the duration configured by the service, the value is used as the duration of refresh tokens issued to the client application. Note that the duration of refresh tokens can be controlled by the scope attribute `refresh_token.duration`, too. Authlete chooses the minimum value among the candidates. idTokenDuration: type: integer format: int64 description: | The value of the duration of ID tokens per client in seconds. In normal cases, the value of the service's `idTokenDuration` property is used as the duration of ID tokens issued by the service. However, if this `idTokenDuration` property holds a non-zero positive number and its value is less than the duration configured by the service, the value is used as the duration of ID tokens issued to the client application. Note that the duration of refresh tokens can be controlled by the scope attribute `id_token.duration`, too. Authlete chooses the minimum value among the candidates. tokenExchangePermitted: type: boolean description: | Get the flag indicating whether the client is explicitly given a permission to make token exchange requests ([RFC 8693][https://www.rfc-editor.org/rfc/rfc8693.html]) client: type: object additionalProperties: true example: number: 1140735077 serviceNumber: 715948317 clientName: My Test Client clientId: '1140735077' clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ clientType: PUBLIC redirectUris: - https://example.com/callback responseTypes: - CODE grantTypes: - AUTHORIZATION_CODE properties: number: type: integer format: int32 readOnly: true description: | The sequential number of the client. The value of this property is assigned by Authlete. serviceNumber: type: integer format: int32 readOnly: true description: | The sequential number of the service of the client application. The value of this property is assigned by Authlete. clientName: type: string description: | The name of the client application. This property corresponds to `client_name` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). clientNames: type: array items: $ref: '#/components/schemas/tagged_value' description: | Client names with language tags. If the client application has different names for different languages, this property can be used to register the names. description: type: string description: The description about the client application. descriptions: type: array items: $ref: '#/components/schemas/tagged_value' description: | Descriptions about the client application with language tags. If the client application has different descriptions for different languages, this property can be used to register the descriptions. clientId: type: integer format: int64 readOnly: true description: The client identifier used in Authlete API calls. The value of this property is assigned by Authlete. clientSecret: type: string readOnly: true description: | The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete. x-mint: metadata: description: "The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete." content: | Note that Authlete issues a client secret even to a "public" client application, but the client application should not use the client secret unless it changes its client type to "confidential". That is, a public client application should behave as if it had not been issued a client secret. To be specific, a token request from a public client of Authlete should not come along with a client secret although [RFC 6749, 3.2.1. Client Authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.1) says as follows. > Confidential clients or other clients issued client credentials MUST authenticate with the authorization server as described in Section 2.3 when making requests to the token endpoint. clientIdAlias: type: string description: | The value of the client's `client_id` property used in OAuth and OpenID Connect calls. By default, this is a string version of the `clientId` property. clientIdAliasEnabled: type: boolean description: Deprecated. Always set to `true`. clientType: $ref: '#/components/schemas/client_type' applicationType: $ref: '#/components/schemas/application_type' logoUri: type: string description: | The URL pointing to the logo image of the client application. This property corresponds to `logo_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). logoUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | Logo image URLs with language tags. If the client application has different logo images for different languages, this property can be used to register URLs of the images. contacts: type: array items: type: string description: | An array of email addresses of people responsible for the client application. This property corresponds to contacts in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). tlsClientCertificateBoundAccessTokens: type: boolean description: | The flag to indicate whether this client use TLS client certificate bound access tokens. dynamicallyRegistered: type: boolean readOnly: true description: | The flag to indicate whether this client has been registered dynamically. For more details, see [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). softwareId: type: string description: | The unique identifier string assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. This property corresponds to the `software_id metadata` defined in [2. Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) of [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). developer: type: string description: | The unique identifier of the developer who created this client application. softwareVersion: type: string description: | The version identifier string for the client software identified by the software ID. This property corresponds to the software_version metadata defined in [2. Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) of [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). registrationAccessTokenHash: type: string description: | The hash of the registration access token for this client. createdAt: type: integer format: int64 readOnly: true description: The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01). modifiedAt: type: integer format: int64 readOnly: true description: The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). grantTypes: type: array items: $ref: '#/components/schemas/grant_type' description: | A string array of grant types which the client application declares that it will restrict itself to using. This property corresponds to `grant_types` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). responseTypes: type: array items: $ref: '#/components/schemas/response_type' description: | A string array of response types which the client application declares that it will restrict itself to using. This property corresponds to `response_types` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). redirectUris: type: array items: type: string description: | Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows. x-mint: metadata: description: "Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows." content: | **Requirements by RFC 6749** (From [RFC 6749, 3.1.2. Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2)) - Must be an absolute URI. - Must not have a fragment component. **Requirements by OpenID Connect** (From "[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), application_type") - The scheme of the redirect URI used for Implicit Grant by a client application whose application is `web` must be `https`. This is checked at runtime by Authlete. - The hostname of the redirect URI used for Implicit Grant by a client application whose application type is `web` must not be `localhost`. This is checked at runtime by Authlete. - The scheme of the redirect URI used by a client application whose application type is `native` must be either (1) a custom scheme or (2) `http`, which is allowed only when the hostname part is `localhost`. This is checked at runtime by Authlete. ## Requirements by Authlete - Must consist of printable ASCII letters only. - Must not exceed 200 letters. Note that Authlete allows the application type to be `null`. In other words, a client application does not have to choose `web` or `native` as its application type. If the application type is `null`, the requirements by OpenID Connect are not checked at runtime. An authorization request from a client application which has not registered any redirect URI fails unless at least all the following conditions are satisfied. - The client type of the client application is `confidential`. - The value of `response_type` request parameter is `code`. - The authorization request has the `redirect_uri` request parameter. - The value of `scope` request parameter does not contain `openid`. RFC 6749 allows partial match of redirect URI under some conditions (see [RFC 6749, 3.1.2.2. Registration Requirements](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2.2) for details), but OpenID Connect requires exact match. authorizationSignAlg: $ref: '#/components/schemas/jws_alg' authorizationEncryptionAlg: $ref: '#/components/schemas/jwe_alg' authorizationEncryptionEnc: $ref: '#/components/schemas/jwe_enc' tokenAuthMethod: $ref: '#/components/schemas/client_auth_method' tokenAuthSignAlg: $ref: '#/components/schemas/jws_alg' selfSignedCertificateKeyId: type: string description: | The key ID of a JWK containing a self-signed certificate of this client. tlsClientAuthSubjectDn: type: string description: | The string representation of the expected subject distinguished name of the certificate this client will use in mutual TLS authentication. See `tls_client_auth_subject_dn` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client Registration" for details. tlsClientAuthSanDns: type: string description: | The string representation of the expected DNS subject alternative name of the certificate this client will use in mutual TLS authentication. See `tls_client_auth_san_dns` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client Registration" for details. tlsClientAuthSanUri: type: string description: | The string representation of the expected URI subject alternative name of the certificate this client will use in mutual TLS authentication. See `tls_client_auth_san_uri` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client Registration" for details. tlsClientAuthSanIp: type: string description: | The string representation of the expected IP address subject alternative name of the certificate this client will use in mutual TLS authentication. See `tls_client_auth_san_ip` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client Registration" for details. tlsClientAuthSanEmail: type: string description: | The string representation of the expected email address subject alternative name of the certificate this client will use in mutual TLS authentication. See `tls_client_auth_san_email` in "Mutual TLS Profiles for OAuth Clients, 2.3. Dynamic Client Registration" for details. parRequired: type: boolean description: | The flag to indicate whether this client is required to use the pushed authorization request endpoint. This property corresponds to the `require_pushed_authorization_requests` client metadata defined in "OAuth 2.0 Pushed Authorization Requests". requestObjectRequired: type: boolean description: | The flag to indicate whether authorization requests from this client are always required to utilize a request object by using either `request` or `request_uri` request parameter. If this flag is set to `true` and the service's `traditionalRequestObjectProcessingApplied` is set to `false`, authorization requests from this client are processed as if `require_signed_request_object` client metadata of this client is `true`. The metadata is defined in "JAR (JWT Secured Authorization Request)". requestSignAlg: $ref: '#/components/schemas/jws_alg' requestEncryptionAlg: $ref: '#/components/schemas/jwe_alg' requestEncryptionEnc: $ref: '#/components/schemas/jwe_enc' requestUris: type: array items: type: string description: | An array of URLs each of which points to a request object. Authlete requires that URLs used as values for `request_uri` request parameter be pre-registered. This property is used for the pre-registration. See [OpenID Connect Core 1.0, 6.2. Passing a Request Object by Reference](https://openid.net/specs/openid-connect-core-1_0.html#RequestUriParameter) for details. defaultMaxAge: type: integer format: int32 description: | The default maximum authentication age in seconds. This value is used when an authorization request from the client application does not have `max_age` request parameter. This property corresponds to `default_max_age` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). defaultAcrs: type: array items: type: string description: | The default ACRs (Authentication Context Class References). This value is used when an authorization request from the client application has neither `acr_values` request parameter nor `acr` claim in claims request parameter. idTokenSignAlg: $ref: '#/components/schemas/jws_alg' idTokenEncryptionAlg: $ref: '#/components/schemas/jwe_alg' idTokenEncryptionEnc: $ref: '#/components/schemas/jwe_enc' authTimeRequired: type: boolean description: | The flag to indicate whether this client requires `auth_time` claim to be embedded in the ID token. This property corresponds to `require_auth_time` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). subjectType: $ref: '#/components/schemas/subject_type' sectorIdentifierUri: type: string description: | The value of the sector identifier URI. This represents the `sector_identifier_uri` client metadata which is defined in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) derivedSectorIdentifier: type: string readOnly: true description: | The sector identifier host component as derived from either the `sector_identifier_uri` or the registered redirect URI. If no `sector_identifier_uri` is registered and multiple redirect URIs are also registered, the value of this property is `null`. jwksUri: type: string description: | The URL pointing to the JWK Set of the client application. The content pointed to by the URL is JSON which complies with the format described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application. x-mint: metadata: description: "The URL pointing to the JWK Set of the client application. The content pointed to by the URL is JSON which complies with the format described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application." content: | If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints) and/or signs request objects, it must make available its JWK Set containing public keys for the encryption and/or the signature at the URL of `jwksUri`. The service (Authlete) fetches the JWK Set from the URL as necessary. [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both properties to be registered at the same time. However, Authlete does not use the content of `jwks` when `jwksUri` is registered. This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). jwks: type: string description: | The content of the JWK Set of the client application. The format is described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application. x-mint: metadata: description: "The content of the JWK Set of the client application. The format is described in [JSON Web Key (JWK), 5. JWK Set Format](https://datatracker.ietf.org/doc/html/rfc7517#section-5). The JWK Set must not include private keys of the client application." content: | [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) says that `jwks` must not be used when the client can use `jwks_uri`, but Authlete allows both properties to be registered at the same time. However, Authlete does not use the content of `jwks` when `jwksUri` is registered. This property corresponds to `jwks_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). userInfoSignAlg: nullable: true $ref: '#/components/schemas/jws_alg' userInfoEncryptionAlg: nullable: true $ref: '#/components/schemas/jwe_alg' userInfoEncryptionEnc: nullable: true $ref: '#/components/schemas/jwe_enc' loginUri: type: string description: | The URL which a third party can use to initiate a login by the client application. This property corresponds to `initiate_login_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). tosUri: type: string description: | The URL pointing to the "Terms Of Service" page. This property corresponds to `tos_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). tosUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | URLs of "Terms Of Service" pages with language tags. If the client application has different "Terms Of Service" pages for different languages, this property can be used to register the URLs. policyUri: type: string description: | The URL pointing to the page which describes the policy as to how end-user's profile data is used. This property corresponds to `policy_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). policyUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | URLs of policy pages with language tags. If the client application has different policy pages for different languages, this property can be used to register the URLs. clientUri: type: string description: | The URL pointing to the home page of the client application. This property corresponds to `client_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). clientUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | Home page URLs with language tags. If the client application has different home pages for different languages, this property can be used to register the URLs. bcDeliveryMode: type: string description: | The backchannel token delivery mode. This property corresponds to the `backchannel_token_delivery_mode` metadata. The backchannel token delivery mode is defined in the specification of "CIBA (Client Initiated Backchannel Authentication)". bcNotificationEndpoint: type: string description: | The backchannel client notification endpoint. This property corresponds to the `backchannel_client_notification_endpoint` metadata. The backchannel token delivery mode is defined in the specification of "CIBA (Client Initiated Backchannel Authentication)". bcRequestSignAlg: $ref: '#/components/schemas/jws_alg' bcUserCodeRequired: type: boolean description: | The boolean flag to indicate whether a user code is required when this client makes a backchannel authentication request. This property corresponds to the `backchannel_user_code_parameter` metadata. attributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this client. extension: $ref: '#/components/schemas/client_extension' authorizationDetailsTypes: type: array items: type: string description: | The authorization details types that this client may use as values of the `type` field in `authorization_details`. This property corresponds to the `authorization_details_types` metadata. See [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) for details. Note that the property name was renamed from authorizationDataTypes to authorizationDetailsTypes to align with the change made by the 5th draft of the RAR specification. customMetadata: type: string description: | The custom client metadata in JSON format. x-mint: metadata: description: "The custom client metadata in JSON format." content: | Standard specifications define client metadata as necessary. The following are such examples. * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) Standard client metadata included in Client Registration Request and Client Update Request (cf. [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, set to corresponding properties of the client application. For example, the value of the `client_name` client metadata in Client Registration/Update Request is set to the clientName property. On the other hand, unrecognized client metadata are discarded. By listing up custom client metadata in advance by using the `supportedCustomClientMetadata` property of Service, Authlete can recognize them and stores their values into the database. The stored custom client metadata values can be referenced by this property. frontChannelRequestObjectEncryptionRequired: type: boolean description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. x-mint: metadata: description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." content: | This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/). Unecrypted request objects are accepted at the endpoint even if this flag is `true`. This flag does not indicate whether a request object is always required. There is a different flag, `requestObjectRequired`, for the purpose. Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` flag of the service is `true`. requestObjectEncryptionAlgMatchRequired: type: boolean description: | The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. x-mint: metadata: description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata." content: | The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_alg > > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects. The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present." The property that represents the client metadata is `requestEncryptionAlg`. See the description of `requestEncryptionAlg` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired` flag of the service is `true`. requestObjectEncryptionEncMatchRequired: type: boolean description: | The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. x-mint: metadata: description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata." content: | The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_enc > > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided. The property that represents the client metadata is `requestEncryptionEnc`. See the description of `requestEncryptionEnc` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired` flag of the service is `true`. digestAlgorithm: type: string description: | The digest algorithm that this client requests the server to use when it computes digest values of [external attachments](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#name-external-attachments), which may be referenced from within ID tokens or userinfo responses (or any place that can have the `verified_claims` claim). Possible values are listed in the [Hash Algorithm Registry](https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg) of IANA (Internet Assigned Numbers Authority), but the server does not necessarily support all the values there. When this property is omitted, `sha-256` is used as the default algorithm. This property corresponds to the `digest_algorithm` client metadata which was defined by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html). singleAccessTokenPerSubject: type: boolean description: | If `Enabled` is selected, an attempt to issue a new access token invalidates existing access tokens that are associated with the same combination of subject and client. Note that, however, attempts by Client Credentials Flow do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user's subject. Even if `Disabled` is selected here, single access token per subject is effective if `singleAccessTokenPerSubject` of the `Service` this client belongs to is Enabled. pkceRequired: type: boolean description: | The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow. If `true`, `code_challenge` request parameter is always required for authorization requests using Authorization Code Flow. See [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients) for details about `code_challenge` request parameter. pkceS256Required: type: boolean description: | The flag to indicate whether `S256` is always required as the code challenge method whenever [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636) is used. If this flag is set to `true`, `code_challenge_method=S256` must be included in the authorization request whenever it includes the `code_challenge` request parameter. Neither omission of the `code_challenge_method` request parameter nor use of plain (`code_challenge_method=plain`) is allowed. dpopRequired: type: boolean description: | If the DPoP is required for this client automaticallyRegistered: type: boolean description: | The flag indicating whether this client was registered by the "automatic" client registration of OIDC Federation. explicitlyRegistered: type: boolean description: | The flag indicating whether this client was registered by the "explicit" client registration of OIDC Federation. rsRequestSigned: type: boolean description: | The flag indicating whether this service signs responses from the resource server. rsSignedRequestKeyId: type: string description: | The key ID of a JWK containing the public key used by this client to sign requests to the resource server. clientRegistrationTypes: type: array items: $ref: '#/components/schemas/client_registration_type' description: | The client registration types that the client has declared it may use. organizationName: type: string description: | The human-readable name representing the organization that manages this client. This property corresponds to the organization_name client metadata that is defined in OpenID Connect Federation 1.0. signedJwksUri: type: string description: | The URI of the endpoint that returns this client's JWK Set document in the JWT format. This property corresponds to the `signed_jwks_uri` client metadata defined in OpenID Connect Federation 1.0. entityId: type: string description: | the entity ID of this client. trustAnchorId: type: string description: | The entity ID of the trust anchor of the trust chain that was used when this client was registered or updated by the mechanism defined in OpenID Connect Federation 1.0 trustChain: type: array items: type: string description: | The trust chain that was used when this client was registered or updated by the mechanism defined in OpenID Connect Federation 1.0 trustChainExpiresAt: type: integer format: int64 description: | the expiration time of the trust chain that was used when this client was registered or updated by the mechanism defined in OpenID Connect Federation 1.0. The value is represented as milliseconds elapsed since the Unix epoch (1970-01-01). trustChainUpdatedAt: type: integer format: int64 description: | the time at which the trust chain was updated by the mechanism defined in OpenID Connect Federation 1.0 locked: type: boolean description: | The flag which indicates whether this client is locked. credentialOfferEndpoint: type: string description: | The URL of the credential offer endpoint at which this client (wallet) receives a credential offer from the credential issuer. fapiModes: type: array items: $ref: '#/components/schemas/fapi_mode' description: | The FAPI modes for this client. x-mint: metadata: description: "The FAPI modes for this client." content: | When the value of this property is not `null`, Authlete always processes requests from this client based on the specified FAPI modes if the FAPI feature is enabled in Authlete, the FAPI profile is supported by the service, and the FAPI modes for the service are set to `null`. For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete always processes requests from this client based on "Financial-grade API Security Profile 1.0 - Part 2: Advanced" if the FAPI feature is enabled in Authlete, the FAPI profile is supported by the service, and the FAPI modes for the service are set to `null`. responseModes: type: array items: type: string enum: - QUERY - FRAGMENT - FORM_POST - JWT - QUERY_JWT - FRAGMENT_JWT - FORM_POST_JWT description: The response modes that this client may use. credentialResponseEncryptionRequired: type: boolean description: True if credential responses to this client must be always encrypted. mtlsEndpointAliasesUsed: type: boolean description: | The flag indicating whether the client intends to prefer mutual TLS endpoints over non-MTLS endpoints. This property corresponds to the `use_mtls_endpoint_aliases` client metadata that is defined in [FAPI 2.0 Security Profile, 8.1.1. use_mtls_endpoint_aliases](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-8.1.1). inScopeForTokenMigration: type: boolean description: | The flag indicating whether this client is in scope for token migration operations. metadataDocumentLocation: type: string format: uri description: | Location of the Client ID Metadata Document that was used for this client. metadataDocumentExpiresAt: type: integer format: int64 description: | Expiration time of the metadata document (UNIX time in milliseconds). metadataDocumentUpdatedAt: type: integer format: int64 description: | Last-updated time of the metadata document (UNIX time in milliseconds). discoveredByMetadataDocument: type: boolean description: | Indicates whether this client was discovered via a Client ID Metadata Document. clientSource: type: string description: | Source of this client record. enum: - DYNAMIC_REGISTRATION - AUTOMATIC_REGISTRATION - EXPLICIT_REGISTRATION - METADATA_DOCUMENT - STATIC_REGISTRATION delivery_mode: type: string enum: - PING - POLL - PUSH display: type: string description: | The display mode which the client application requests by `display` request parameter. When the authorization request does not have `display` request parameter, `PAGE` is set as the default value. It is ensured that the value of `display` is one of the supported display modes which are specified by `supportedDisplays` configuration parameter of the service. If the display mode specified by the authorization request is not supported, an error is raised. Values for this property correspond to the values listed in "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), display". enum: - PAGE - POPUP - TOUCH - WAP dynamic_scope: type: object properties: name: type: string description: The scope name. value: type: string description: The scope value. grant_type: type: string description: | The grant type of the access token when the access token was created. enum: - AUTHORIZATION_CODE - IMPLICIT - PASSWORD - CLIENT_CREDENTIALS - REFRESH_TOKEN - CIBA - DEVICE_CODE - TOKEN_EXCHANGE - JWT_BEARER - PRE_AUTHORIZED_CODE jwe_alg: type: string nullable: true description: | this is the 'alg' header value for encrypted JWT tokens. Depending upon the context, this refers to key transport scheme to be used by the client and by the server. For instance: - as `authorizationEncryptionAlg` value, it refers to the encoding algorithm used by server for transporting they keys on JARM objects - as `requestEncryptionAlg` value, it refers to the expected key transport encoding algorithm that server expect from client when encrypting a Request Object - as `idTokenEncryptionAlg` value, it refers to the algorithm used by the server to key transport of id_tokens **Please note that some of the algorithms are more secure than others, some are not supported very well cross platforms and some (like RSA1_5) is known to be weak**. enum: - RSA1_5 - RSA_OAEP - RSA_OAEP_256 - A128KW - A192KW - A256KW - DIR - ECDH_ES - ECDH_ES_A128KW - ECDH_ES_A192KW - ECDH_ES_A256KW - A128GCMKW - A192GCMKW - A256GCMKW - PBES2_HS256_A128KW - PBES2_HS384_A192KW - PBES2_HS512_A256KW jwe_enc: type: string nullable: true description: | This is the encryption algorithm to be used when encrypting a JWT on client or server side. Depending upon the context, this refers to encryption done by the client or by the server. For instance: - as `authorizationEncryptionEnc` value, it refers to the encryption algorithm used by server when creating a JARM response - as `requestEncryptionEnc` value, it refers to the expected encryption algorithm used by the client when encrypting a Request Object - as `idTokenEncryptionEnc` value, it refers to the algorithm used by the server to encrypt id_tokens enum: - A128CBC_HS256 - A192CBC_HS384 - A256CBC_HS512 - A128GCM - A192GCM - A256GCM jws_alg: type: string nullable: true description: | The signature algorithm for JWT. This value is represented on 'alg' attribute of the header of JWT. it's semantics depends upon where is this defined, for instance: - as service accessTokenSignAlg value, it defines that access token are JWT and the algorithm used to sign it. Check your [KB article](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/jwt-based-access-token). - as client authorizationSignAlg value, it represents the signature algorithm used when [creating a JARM response](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/enabling-jarm). - or as client requestSignAlg value, it specifies which is the expected signature used by [client on a Request Object](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/request-objects). enum: - NONE - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - ES256 - ES384 - ES512 - PS256 - PS384 - PS512 - ES256K - EdDSA named_uri: type: object properties: name: type: string uri: type: string format: uri pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. prompt: type: string description: | The prompt that the UI displayed to the end-user must satisfy as the minimum level. This value comes from `prompt` request parameter. When the authorization request does not contain `prompt` request parameter, `CONSENT` is used as the default value. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), prompt" for `prompt` request parameter. enum: - NONE - LOGIN - CONSENT - SELECT_ACCOUNT - CREATE property: type: object properties: key: type: string description: The key part. value: type: string description: The value part. hidden: type: boolean description: | The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. response_type: type: string enum: - NONE - CODE - TOKEN - ID_TOKEN - CODE_TOKEN - CODE_ID_TOKEN - ID_TOKEN_TOKEN - CODE_ID_TOKEN_TOKEN scope: type: object properties: name: type: string description: The name of the scope. defaultEntry: type: boolean description: '`true` to mark the scope as default. Scopes marked as default are regarded as requested when an authorization request from a client application does not contain scope request parameter. ' description: type: string description: The description about the scope. descriptions: type: array description: The descriptions about this scope in multiple languages. items: $ref: '#/components/schemas/tagged_value' attributes: type: array description: The attributes of the scope. items: $ref: '#/components/schemas/pair' service_profile: type: string enum: - FAPI - OPEN_BANKING service: type: object example: number: 715948317 serviceName: My Test Service issuer: https://example.com supportedScopes: - profile - email - openid supportedResponseTypes: - CODE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN properties: number: type: integer format: int32 readOnly: true description: The sequential number of the service. The value of this property is assigned by Authlete. serviceName: type: string description: The name of this service. issuer: type: string description: | The issuer identifier of the service. A URL that starts with https:// and has no query or fragment component. The value of this property is used as `iss` claim in an [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and `issuer` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). description: type: string description: The description about the service. apiKey: type: integer format: int64 readOnly: true description: The service ID used in Authlete API calls. The value of this property is assigned by Authlete. apiSecret: type: string readOnly: true description: | The API secret of this service. This value is assigned by Authlete and is used for service authentication in API calls. tokenBatchNotificationEndpoint: type: string format: uri description: | The endpoint for batch token notifications. This endpoint is called when multiple tokens are issued or revoked in a batch operation. clientAssertionAudRestrictedToIssuer: type: boolean description: | The flag indicating whether the audience of client assertion JWTs must match the issuer identifier of this service. serviceOwnerNumber: type: integer format: int32 readOnly: true description: | The number of the organization that owns this service. This value is assigned by Authlete. clientsPerDeveloper: type: integer format: int32 description: | The maximum number of client applications that a developer can have. developerAuthenticationCallbackEndpoint: type: string format: uri description: | The endpoint for developer authentication callbacks. This is used when developers log into the developer portal. developerAuthenticationCallbackApiKey: type: string description: | The API key for basic authentication at the developer authentication callback endpoint. developerAuthenticationCallbackApiSecret: type: string description: | The API secret for basic authentication at the developer authentication callback endpoint. supportedSnses: type: array items: type: string enum: - FACEBOOK description: | Social login services (SNS) that this service supports for end-user authentication. snsCredentials: type: array items: $ref: '#/components/schemas/sns_credentials' description: | The credentials for social login services (SNS) that are used for end-user authentication. clientIdAliasEnabled: type: boolean description: Deprecated. Always `true`. metadata: type: array items: $ref: '#/components/schemas/pair' description: | The `metadata` of the service. The content of the returned array depends on contexts. The predefined service metadata is listed in the following table. | Key | Description | | --- | --- | | `clientCount` | The number of client applications which belong to this service. | createdAt: type: integer format: int64 readOnly: true description: | The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (`1970-01-01`). modifiedAt: type: integer format: int64 readOnly: true description: | The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). authenticationCallbackEndpoint: type: string format: uri description: | A Web API endpoint for user authentication which is to be prepared on the service side. The endpoint must be implemented if you do not implement the UI at the authorization endpoint but use the one provided by Authlete. The user authentication at the authorization endpoint provided by Authlete is performed by making a `POST` request to this endpoint. authenticationCallbackApiKey: type: string description: | API key for basic authentication at the authentication callback endpoint. If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the authentication callback endpoint. authenticationCallbackApiSecret: type: string description: API secret for `basic` authentication at the authentication callback endpoint. supportedAcrs: readOnly: true type: array items: type: string description: | Values of acrs (authentication context class references) that the service supports. The value of this property is used as `acr_values_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedGrantTypes: type: array items: $ref: '#/components/schemas/grant_type' description: | Values of `grant_type` request parameter that the service supports. The value of this property is used as `grant_types_supported property` in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedResponseTypes: type: array items: $ref: '#/components/schemas/response_type' description: | Values of `response_type` request parameter that the service supports. Valid values are listed in Response Type. The value of this property is used as `response_types_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedAuthorizationDetailsTypes: type: array items: type: string description: | The supported data types that can be used as values of the type field in `authorization_details`. This property corresponds to the `authorization_details_types_supported` metadata. See "OAuth 2.0 Rich Authorization Requests" (RAR) for details. supportedServiceProfiles: type: array items: $ref: '#/components/schemas/service_profile' description: | The profiles that this service supports. errorDescriptionOmitted: type: boolean description: | The flag to indicate whether the `error_description` response parameter is omitted. According to [RFC 6749](https://tools.ietf.org/html/rfc6749), an authorization server may include the `error_description` response parameter in error responses. If `true`, Authlete does not embed the `error_description` response parameter in error responses. errorUriOmitted: type: boolean description: | The flag to indicate whether the `error_uri` response parameter is omitted. According to [RFC 6749](https://tools.ietf.org/html/rfc6749), an authorization server may include the `error_uri` response parameter in error responses. If `true`, Authlete does not embed the `error_uri` response parameter in error responses. authorizationEndpoint: type: string format: uri description: | The authorization endpoint of the service. A URL that starts with `https://` and has no fragment component. For example, `https://example.com/auth/authorization`. The value of this property is used as `authorization_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). directAuthorizationEndpointEnabled: type: boolean description: | The flag to indicate whether the direct authorization endpoint is enabled or not. The path of the endpoint is `/api/auth/authorization/direct/service-api-key`. supportedUiLocales: type: array items: type: string description: | UI locales that the service supports. Each element is a language tag defined in [RFC 5646](https://tools.ietf.org/html/rfc5646). For example, `en-US` and `ja-JP`. The value of this property is used as `ui_locales_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedDisplays: type: array items: $ref: '#/components/schemas/display' description: | Values of `display` request parameter that service supports. The value of this property is used as `display_values_supported` property in the Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). pkceRequired: type: boolean description: | The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow. If `true`, `code_challenge` request parameter is always required for authorization requests using Authorization Code Flow. See [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients) for details about `code_challenge` request parameter. pkceS256Required: type: boolean description: | The flag to indicate whether `S256` is always required as the code challenge method whenever [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636) is used. If this flag is set to `true`, `code_challenge_method=S256` must be included in the authorization request whenever it includes the `code_challenge` request parameter. Neither omission of the `code_challenge_method` request parameter nor use of plain (`code_challenge_method=plain`) is allowed. authorizationResponseDuration: type: integer format: int64 description: | The duration of authorization response JWTs in seconds. [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`, `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This property is used to compute the value of the `exp` claim of the JWT. authorizationCodeDuration: type: integer format: int64 description: | The duration of authorization codes in seconds. tokenEndpoint: type: string format: uri description: | The [token endpoint](https://tools.ietf.org/html/rfc6749#section-3.2) of the service. A URL that starts with `https://` and has not fragment component. For example, `https://example.com/auth/token`. The value of this property is used as `token_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). directTokenEndpointEnabled: type: boolean description: | The flag to indicate whether the direct token endpoint is enabled or not. The path of the endpoint is `/api/auth/token/direct/service-api-key`. supportedTokenAuthMethods: type: array items: $ref: '#/components/schemas/client_auth_method' description: | Client authentication methods supported by the token endpoint of the service. The value of this property is used as `token_endpoint_auth_methods_supports` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). missingClientIdAllowed: type: boolean description: | The flag to indicate token requests from public clients without the `client_id` request parameter are allowed when the client can be guessed from `authorization_code` or `refresh_token`. This flag should not be set unless you have special reasons. revocationEndpoint: type: string format: uri description: | The [revocation endpoint](https://tools.ietf.org/html/rfc7009) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/revocation`. directRevocationEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct revocation endpoint is enabled or not. The URL of the endpoint is `/api/auth/revocation/direct/service-api-key`. ' supportedRevocationAuthMethods: type: array items: $ref: '#/components/schemas/client_auth_method' description: | Client authentication methods supported at the revocation endpoint. introspectionEndpoint: type: string description: The URI of the introspection endpoint. format: uri directIntrospectionEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is `/api/auth/userinfo/direct/{serviceApiKey}`. ' supportedIntrospectionAuthMethods: type: array description: | Client authentication methods supported at the introspection endpoint. items: $ref: '#/components/schemas/client_auth_method' pushedAuthReqEndpoint: type: string description: | The URI of the pushed authorization request endpoint. This property corresponds to the `pushed_authorization_request_endpoint` metadata defined in "[5. Authorization Server Metadata](https://tools.ietf.org/html/draft-lodderstedt-oauth-par#section-5)" of OAuth 2.0 Pushed Authorization Requests. format: uri pushedAuthReqDuration: type: integer format: int64 description: | The duration of pushed authorization requests in seconds. x-mint: metadata: description: "The duration of pushed authorization requests in seconds." content: | [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par) defines an endpoint (called "pushed authorization request endpoint") which client applications can register authorization requests into and get corresponding URIs (called "request URIs") from. The issued URIs represent the registered authorization requests. The client applications can use the URIs as the value of the `request_uri` request parameter in an authorization request. The property represents the duration of registered authorization requests and is used as the value of the `expires_in` parameter in responses from the pushed authorization request endpoint. parRequired: type: boolean description: | The flag to indicate whether this service requires that clients use the pushed authorization request endpoint. This property corresponds to the `require_pushed_authorization_requests` server metadata defined in [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par). requestObjectRequired: type: boolean description: | The flag to indicate whether this service requires that authorization requests always utilize a request object by using either request or `request_uri` request parameter. If this flag is set to `true` and the value of `traditionalRequestObjectProcessingApplied` is `false`, the value of `require_signed_request_object` server metadata of this service is reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured Authorization Request). That `require_signed_request_object` is `true` means that authorization requests which don't conform to the JAR specification are rejected. traditionalRequestObjectProcessingApplied: type: boolean description: | The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request). x-mint: metadata: description: "The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request)." content: | Differences between rules in OpenID Connect Core 1.0 and ones in JAR are as follows. - JAR requires that a request object be always -signed. - JAR does not allow request parameters outside a request object to be referred to. - OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter. - OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an - OIDC request even if the request object includes the request parameter. If this flag is set to `false` and the value of `requestObjectRequired` is `true`, the value of `require_signed_request_object` server metadata of this service is reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured Authorization Request). That `require_signed_request_object` is `true` means that authorization requests which don't conform to the JAR specification are rejected. mutualTlsValidatePkiCertChain: type: boolean description: | The flag to indicate whether this service validates certificate chains during PKI-based client mutual TLS authentication. trustedRootCertificates: type: array items: type: string description: | The list of root certificates trusted by this service for PKI-based client mutual TLS authentication. mtlsEndpointAliases: type: array items: $ref: '#/components/schemas/named_uri' description: | The MTLS endpoint aliases. x-mint: metadata: description: "The MTLS endpoint aliases." content: | This property corresponds to the mtls_endpoint_aliases metadata defined in "5. Metadata for Mutual TLS Endpoint Aliases" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/). The aliases will be embedded in the response from the discovery endpoint like the following. ```json { ......, "mtls_endpoint_aliases": { "token_endpoint": "https://mtls.example.com/token", "revocation_endpoint": "https://mtls.example.com/revo", "introspection_endpoint": "https://mtls.example.com/introspect" } } ``` accessTokenType: type: string description: | The access token type. This value is used as the value of `token_type` property in access token responses. If this service complies with [RFC 6750](https://tools.ietf.org/html/rfc6750), the value of this property should be `Bearer`. See [RFC 6749 (OAuth 2.0), 7.1. Access Token Types](https://tools.ietf.org/html/rfc6749#section-7.1) for details. tlsClientCertificateBoundAccessTokens: type: boolean description: | The flag to indicate whether this service supports issuing TLS client certificate bound access tokens. accessTokenDuration: type: integer format: int64 description: | The duration of access tokens in seconds. This value is used as the value of `expires_in` property in access token responses. `expires_in` is defined [RFC 6749, 5.1. Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1). singleAccessTokenPerSubject: type: boolean description: | The flag to indicate whether the number of access tokens per subject (and per client) is at most one or can be more. If `true`, an attempt to issue a new access token invalidates existing access tokens that are associated with the same subject and the same client. Note that, however, attempts by [Client Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.4) do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user's subject. Also note that an attempt by [Refresh Token Flow](https://tools.ietf.org/html/rfc6749#section-6) invalidates the coupled access token only and this invalidation is always performed regardless of whether the value of this setting item is `true` or `false`. accessTokenSignAlg: $ref: '#/components/schemas/jws_alg' accessTokenSignatureKeyId: type: string description: | The key ID to identify a JWK used for signing access tokens. A JWK Set can be registered as a property of a service. A JWK Set can contain 0 or more JWKs. Authlete Server has to pick up one JWK for signing from the JWK Set when it generates a JWT-based access token. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for access token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. refreshTokenDuration: type: integer format: int64 description: The duration of refresh tokens in seconds. The related specifications have no requirements on refresh token duration, but Authlete sets expiration for refresh tokens. refreshTokenDurationKept: type: boolean description: | The flag to indicate whether the remaining duration of the used refresh token is taken over to the newly issued refresh token. refreshTokenDurationReset: type: boolean description: | The flag which indicates whether duration of refresh tokens are reset when they are used even if the `refreshTokenKept` property of this service set to is `true` (= even if "Refresh Token Continuous Use" is "Kept"). This flag has no effect when the `refreshTokenKept` property is set to `false`. In other words, if this service issues a new refresh token on every refresh token request, the refresh token will have fresh duration (unless `refreshTokenDurationKept` is set to `true`) and this `refreshTokenDurationReset` property is not referenced. refreshTokenKept: type: boolean description: | The flag to indicate whether a refresh token remains unchanged or gets renewed after its use. If `true`, a refresh token used to get a new access token remains valid after its use. Otherwise, if `false`, a refresh token is invalidated after its use and a new refresh token is issued. See [RFC 6749 6. Refreshing an Access Token](https://tools.ietf.org/html/rfc6749#section-6), as to how to get a new access token using a refresh token. supportedScopes: type: array items: $ref: '#/components/schemas/scope' description: | Scopes supported by the service. x-mint: metadata: description: "Scopes supported by the service." content: | Authlete strongly recommends that the service register at least the following scopes. | Name | Description | | --- | --- | | openid | A permission to get an ID token of an end-user. The `openid` scope appears in [OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Without this scope, Authlete does not allow `response_type` request parameter to have values other than code and token. | | profile | A permission to get information about `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale` and `updated_at` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | email | A permission to get information about `email` and `email_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | address | A permission to get information about address from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details. | | phone | A permission to get information about `phone_number` and `phone_number_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | offline_access | A permission to get information from the user info endpoint even when the end-user is not present. See [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. | The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). scopeRequired: type: boolean description: | The flag to indicate whether requests that request no scope are rejected or not. x-mint: metadata: description: "The flag to indicate whether requests that request no scope are rejected or not." content: | When a request has no explicit `scope` parameter and the service's pre-defined default scope set is empty, the authorization server regards the request requests no scope. When this flag is set to `true`, requests that request no scope are rejected. The requirement below excerpted from [RFC 6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3) does not explicitly mention the case where the default scope set is empty. > If the client omits the scope parameter when requesting authorization, the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope. However, if you interpret *"the default scope set exists but is empty"* as *"the default scope set does not exist"* and want to strictly conform to the requirement above, this flag has to be `true`. idTokenDuration: type: integer format: int64 description: | 'The duration of [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)s in seconds. This value is used to calculate the value of `exp` claim in an ID token.' allowableClockSkew: type: integer format: int32 description: | The allowable clock skew between the server and clients in seconds. The clock skew is taken into consideration when time-related claims in a JWT (e.g. `exp`, `iat`, `nbf`) are verified. supportedClaimTypes: type: array items: $ref: '#/components/schemas/claim_type' description: | Claim types supported by the service. Valid values are listed in Claim Type. Note that Authlete currently doesn't provide any API to help implementations for `AGGREGATED` and `DISTRIBUTED`. The value of this property is used as `claim_types_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedClaimLocales: type: array items: type: string description: | Claim locales that the service supports. Each element is a language tag defined in [RFC 5646](https://tools.ietf.org/html/rfc5646). For example, `en-US` and `ja-JP`. See [OpenID Connect Core 1.0, 5.2. Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) for details. The value of this property is used as `claims_locales_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). supportedClaims: type: array items: type: string description: | Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims. x-mint: metadata: description: "Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims." content: | - `sub` - `name` - `given_name` - `family_name` - `middle_name` - `nickname` - `preferred_username` - `profile` - `picture` - `website` - `email` - `email_verified` - `gender` - `birthdate` - `zoneinfo` - `locale` - `phone_number` - `phone_number_verified` - `address` - `updated_at` The value of this property is used as `claims_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims). claimShortcutRestrictive: type: boolean description: | The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included in the issued ID token only when no access token is issued. x-mint: metadata: description: "The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included in the issued ID token only when no access token is issued." content: | To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), this flag has to be `true`. > The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that results in an Access Token being issued. However, when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token. jwksUri: type: string format: uri description: | The URL of the service's [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) document. For example, `http://example.com/auth/jwks`. Client applications accesses this URL (1) to get the public key of the service to validate the signature of an ID token issued by the service and (2) to get the public key of the service to encrypt an request object of the client application. See [OpenID Connect Core 1.0, 10. Signatures and Encryption](https://openid.net/specs/openid-connect-core-1_0.html#SigEnc) for details. The value of this property is used as `jwks_uri` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). directJwksEndpointEnabled: type: boolean description: | 'The flag to indicate whether the direct jwks endpoint is enabled or not. The path of the endpoint is `/api/service/jwks/get/direct/service-api-key`. ' jwks: type: string description: | The content of the service's [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) document. If this property is not `null` in a `/service/create` request or a `/service/update` request, Authlete hosts the content in the database. This property must not be `null` and must contain pairs of public/private keys if the service wants to support asymmetric signatures for ID tokens and asymmetric encryption for request objects. See [OpenID Connect Core 1.0, 10. Signatures and Encryption](https://openid.net/specs/openid-connect-core-1_0.html#SigEnc) for details. idTokenSignatureKeyId: type: string description: | The key ID to identify a JWK used for ID token signature using an asymmetric key. x-mint: metadata: description: "The key ID to identify a JWK used for ID token signature using an asymmetric key." content: | A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it generates an ID token and signature using an asymmetric key is required. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for ID token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This `idTokenSignatureKeyId` property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), this mechanism is needed. userInfoSignatureKeyId: type: string description: | The key ID to identify a JWK used for user info signature using an asymmetric key. x-mint: metadata: description: "The key ID to identify a JWK used for user info signature using an asymmetric key." content: | A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it is required to sign user info (which is returned from [userinfo endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo)) using an asymmetric key. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for user info signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This `userInfoSignatureKeyId` property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), this mechanism is needed. authorizationSignatureKeyId: type: string description: | The key ID to identify a JWK used for signing authorization responses using an asymmetric key. x-mint: metadata: description: "The key ID to identify a JWK used for signing authorization responses using an asymmetric key." content: | [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`, `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This property is used to compute the value of the `exp` claim of the JWT. Authlete Server searches the JWK Set for a JWK which satisfies conditions for authorization response signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This property exists to specify the key ID. userInfoEndpoint: type: string description: | The [user info endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/userinfo`. The value of this property is used as `userinfo_endpoint` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). format: uri directUserInfoEndpointEnabled: type: boolean description: | The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is `/api/auth/userinfo/direct/service-api-key`. dynamicRegistrationSupported: type: boolean description: | The boolean flag which indicates whether the [OAuth 2.0 Dynamic Client Registration Protocol](https://tools.ietf.org/html/rfc7591) is supported. registrationEndpoint: type: string description: | The [registration endpoint](http://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/registration`. The value of this property is used as `registration_endpoint` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). format: uri registrationManagementEndpoint: type: string description: | The URI of the registration management endpoint. If dynamic client registration is supported, and this is set, this URI will be used as the basis of the client's management endpoint by appending `/clientid}/` to it as a path element. If this is unset, the value of `registrationEndpoint` will be used as the URI base instead. format: uri policyUri: type: string description: | The URL of the "Policy" of the service. The value of this property is used as `op_policy_uri` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). format: uri tosUri: type: string description: | The URL of the "Terms Of Service" of the service. The value of this property is used as `op_tos_uri` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). format: uri serviceDocumentation: type: string description: | The URL of a page where documents for developers can be found. The value of this property is used as `service_documentation` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). format: uri backchannelAuthenticationEndpoint: type: string description: | The URI of backchannel authentication endpoint, which is defined in the specification of [CIBA (Client Initiated Backchannel Authentication)](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html). format: uri supportedBackchannelTokenDeliveryModes: type: array items: $ref: '#/components/schemas/delivery_mode' description: | The supported backchannel token delivery modes. This property corresponds to the `backchannel_token_delivery_modes_supported` metadata. Backchannel token delivery modes are defined in the specification of [CIBA (Client Initiated Backchannel Authentication)](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html). backchannelAuthReqIdDuration: type: integer format: int32 description: | The duration of backchannel authentication request IDs issued from the backchannel authentication endpoint in seconds. This is used as the value of the `expires_in` property in responses from the backchannel authentication endpoint. backchannelPollingInterval: type: integer format: int32 description: | The minimum interval between polling requests to the token endpoint from client applications in seconds. This is used as the value of the `interval` property in responses from the backchannel authentication endpoint. backchannelUserCodeParameterSupported: type: boolean description: | The boolean flag which indicates whether the `user_code` request parameter is supported at the backchannel authentication endpoint. This property corresponds to the `backchannel_user_code_parameter_supported` metadata. backchannelBindingMessageRequiredInFapi: type: boolean description: | The flag to indicate whether the `binding_message` request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API. x-mint: metadata: description: "The flag to indicate whether the `binding_message` request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API." content: | The FAPI-CIBA profile requires that the authorization server _"shall ensure unique authorization context exists in the authorization request or require a `binding_message` in the authorization request"_ (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to set this property to `true`. If this property is set to `false`, the `binding_message` request parameter remains optional even in FAPI context, but in exchange, your authorization server must implement a custom mechanism that ensures each backchannel authentication request has unique context. deviceAuthorizationEndpoint: type: string format: uri description: | The URI of the device authorization endpoint. Device authorization endpoint is defined in the specification of OAuth 2.0 Device Authorization Grant. deviceVerificationUri: type: string format: uri description: | The verification URI for the device flow. This URI is used as the value of the `verification_uri` parameter in responses from the device authorization endpoint. deviceVerificationUriComplete: type: string format: uri description: | The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint. x-mint: metadata: description: "The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint." content: | It is expected that the URI contains a fixed string `USER_CODE` somewhere as a placeholder for a user code. For example, like the following. `https://example.com/device?user_code=USER_CODE` The fixed string is replaced with an actual user code when Authlete builds a verification URI with a user code for the `verification_uri_complete` parameter. If this URI is not set, the `verification_uri_complete` parameter won't appear in device authorization responses. deviceFlowCodeDuration: type: integer format: int32 description: | The duration of device verification codes and end-user verification codes issued from the device authorization endpoint in seconds. This is used as the value of the `expires_in` property in responses from the device authorization endpoint. deviceFlowPollingInterval: type: integer format: int32 description: | The minimum interval between polling requests to the token endpoint from client applications in seconds in device flow. This is used as the value of the `interval` property in responses from the device authorization endpoint. userCodeCharset: $ref: '#/components/schemas/user_code_charset' userCodeLength: type: integer format: int32 description: | The length of end-user verification codes (`user_code`) for Device Flow. supportedTrustFrameworks: type: array items: type: string description: | Trust frameworks supported by this service. This corresponds to the `trust_frameworks_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). supportedEvidence: type: array items: type: string description: | Evidence supported by this service. This corresponds to the `evidence_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). supportedIdentityDocuments: type: array items: type: string description: | Identity documents supported by this service. This corresponds to the `id_documents_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). supportedVerificationMethods: type: array items: type: string description: | Verification methods supported by this service. This corresponds to the `id_documents_verification_methods_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). supportedVerifiedClaims: type: array items: type: string description: | Verified claims supported by this service. This corresponds to the `claims_in_verified_claims_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). verifiedClaimsValidationSchemaSet: $ref: '#/components/schemas/verified_claims_validation_schema' type: string description: | OIDC4IDA / verifiedClaimsValidationSchemaSet attributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service. nbfOptional: type: boolean description: | The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request. x-mint: metadata: description: "The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request." content: | The final version of Financial-grade API was approved in January, 2021. The Part 2 of the final version has new requirements on lifetime of request objects. They require that request objects contain an `nbf` claim and the lifetime computed by `exp` - `nbf` be no longer than 60 minutes. Therefore, when an authorization request is regarded as a FAPI-Part2 request, the request object used in the authorization request must contain an nbf claim. Otherwise, the authorization server rejects the authorization request. When this flag is `true`, the `nbf` claim is treated as an optional claim even when the authorization request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform the validation on lifetime of the request object. Skipping the validation is a violation of the FAPI specification. The reason why this flag has been prepared nevertheless is that the new requirements (which do not exist in the Implementer's Draft 2 released in October, 2018) have big impacts on deployed implementations of client applications and Authlete thinks there should be a mechanism whereby to make the migration from ID2 to Final smooth without breaking live systems. issSuppressed: type: boolean description: | The flag indicating whether generation of the iss response parameter is suppressed. x-mint: metadata: description: "The flag indicating whether generation of the iss response parameter is suppressed." content: | "OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response" has defined a new authorization response parameter, `iss`, as a countermeasure for a certain type of mix-up attacks. The specification requires that the `iss` response parameter always be included in authorization responses unless JARM (JWT Secured Authorization Response Mode) is used. When this flag is `true`, the authorization server does not include the `iss` response parameter in authorization responses. By turning this flag on and off, developers of client applications can experiment the mix-up attack and the effect of the `iss` response parameter. Note that this flag should not be `true` in production environment unless there are special reasons for it. supportedCustomClientMetadata: type: array items: type: string description: | custom client metadata supported by this service. x-mint: metadata: description: "custom client metadata supported by this service." content: | Standard specifications define client metadata as necessary. The following are such examples. * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) Standard client metadata included in Client Registration Request and Client Update Request (cf. [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, stored into Authlete database. On the other hand, unrecognized client metadata are discarded. By listing up custom client metadata in advance by using this property (`supportedCustomClientMetadata`), Authlete can recognize them and stores their values into the database. The stored custom client metadata values can be referenced by `customMetadata`. tokenExpirationLinked: type: boolean description: | The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token. x-mint: metadata: description: "The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token." content: | When a new access token is issued by a refresh token request (= a token request with `grant_type=refresh_token`), the expiration date of the access token may exceed the expiration date of the corresponding refresh token. This behavior itself is not wrong and may happen when `refreshTokenKept` is `true` and/or when `refreshTokenDurationKept` is `true`. When this flag is `true`, the expiration date of an access token never exceeds that of the corresponding refresh token regardless of the calculated duration based on other settings such as `accessTokenDuration`, `accessTokenDuration` in `extension` and `access_token.duration` scope attribute. It is technically possible to set a value which is bigger than the duration of refresh tokens as the duration of access tokens although it is strange. In the case, the duration of an access token becomes longer than the duration of the refresh token which is issued together with the access token. Even if the duration values are configured so, if this flag is `true`, the expiration date of the access token does not exceed that of the refresh token. That is, the duration of the access token will be shortened, and as a result, the access token and the refresh token will have the same expiration date. frontChannelRequestObjectEncryptionRequired: type: boolean description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. x-mint: metadata: description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." content: | This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/). Unecrypted request objects are accepted at the endpoint even if this flag is `true`. This flag does not indicate whether a request object is always required. There is a different flag, `requestObjectRequired`, for the purpose. See the description of `requestObjectRequired` for details. Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` flag of the client is `true`. requestObjectEncryptionAlgMatchRequired: type: boolean description: | The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata of the client that has sent the request object. x-mint: metadata: description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata of the client that has sent the request object." content: | The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_alg > > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects. The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present." The Client's property that represents the client metadata is `requestEncryptionAlg`. See the description of `requestEncryptionAlg` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired` flag of the client is `true`. requestObjectEncryptionEncMatchRequired: type: boolean description: | The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc` client metadata of the client that has sent the request object. x-mint: metadata: description: "The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc` client metadata of the client that has sent the request object." content: | The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_enc > > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided. The Client's property that represents the client metadata is `requestEncryptionEnc`. See the description of `requestEncryptionEnc` for details. Even if this flag is false, the match is required if the `requestObjectEncryptionEncMatchRequired` flag is `true`. hsmEnabled: type: boolean description: | The flag indicating whether HSM (Hardware Security Module) support is enabled for this service. When this flag is `false`, keys managed in HSMs are not used even if they exist. In addition, `/api/hsk/*` APIs reject all requests. Even if this flag is `true`, HSM-related features do not work if the configuration of the Authlete server you are using does not support HSM. hsks: type: array items: $ref: '#/components/schemas/hsk' description: | The information about keys managed on HSMs (Hardware Security Modules). This `hsks` property is output only, meaning that `hsks` in requests to `/api/service/create` API and `/api/service/update` API do not have any effect. The contents of this property is controlled only by `/api/hsk/*` APIs. grantManagementEndpoint: type: string description: | The URL of the grant management endpoint. grantManagementActionRequired: type: boolean description: | The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the `grant_management_action` request parameter. x-mint: metadata: description: "The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the `grant_management_action` request parameter." content: | This property corresponds to the `grant_management_action_required` server metadata defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). Note that setting true to this property will result in blocking all public clients because the specification requires that grant management be usable only by confidential clients for security reasons. unauthorizedOnClientConfigSupported: type: boolean description: | The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate. x-mint: metadata: description: "The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate." content: | The `UNAUTHORIZED` enum value was initially not defined as a possible value of the `action` parameter in an `/api/client/registration` API response. This means that implementations of client `configuration` endpoint were not able to conform to [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html) strictly. For backward compatibility (to avoid breaking running systems), Authlete's `/api/client/registration` API does not return the `UNAUTHORIZED` enum value if this flag is not turned on. The steps an existing implementation of client configuration endpoint has to do in order to conform to the requirement related to "401 Unauthorized" are as follows. 1. Update the Authlete library (e.g. authlete-java-common) your system is using. 2. Update your implementation of client configuration endpoint so that it can handle the `UNAUTHORIZED` action. 3. Turn on this `unauthorizedOnClientConfigSupported` flag. dcrScopeUsedAsRequestable: type: boolean description: | The flag indicating whether the `scope` request parameter in dynamic client registration and update requests (RFC 7591 and RFC 7592) is used as scopes that the client can request. Limiting the range of scopes that a client can request is achieved by listing scopes in the `client.extension.requestableScopes` property and setting the `client.extension.requestableScopesEnabled` property to `true`. This feature is called "requestable scopes". This property affects behaviors of `/api/client/registration` and other family APIs. endSessionEndpoint: type: string format: uri description: | The endpoint for clients ending the sessions. A URL that starts with `https://` and has no fragment component. For example, `https://example.com/auth/endSession`. The value of this property is used as `end_session_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). loopbackRedirectionUriVariable: type: boolean description: | The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback. x-mint: metadata: description: "The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback." content: | When this flag is `true`, if the host component of a redirection URI specified in an authorization request indicates loopback (to be precise, when the host component is localhost, `127.0.0.1` or `::1`), the port number component is ignored when the specified redirection URI is compared to pre-registered ones. This behavior is described in [7.3. Loopback Interface Redirection]( https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html) for Native Apps. [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3) of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration included the full redirection URI, the authorization server MUST compare the two URIs using simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986] (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0 are satisfied, the port number component of loopback redirection URIs can be variable when this flag is `true`. [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3) of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states as follows. > While redirect URIs using localhost (i.e., `"http://localhost:{port}/{path}"`) function similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently listening on network interfaces other than the loopback interface. It is also less susceptible to client-side firewalls and misconfigured host name resolution on the user's device. However, Authlete allows the port number component to be variable in the case of `localhost`, too. It is left to client applications whether they use `localhost` or a literal loopback IP address (`127.0.0.1` for IPv4 or `::1` for IPv6). Section 7.3 and Section 8.3 of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) state that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number component to be variable in other cases (e.g. in the case of the `"https"` scheme), too. requestObjectAudienceChecked: type: boolean description: | The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service. x-mint: metadata: description: "The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service." content: | [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests) of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following statement. > The `aud` value SHOULD be or include the OP's Issuer Identifier URL. Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)) has the following statement. > The value of aud should be the value of the authorization server (AS) issuer, as defined in [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html). As excerpted above, validation on the `aud` claim of request objects is optional. However, if this flag is turned on, Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service and raises an error if they are different. accessTokenForExternalAttachmentEmbedded: type: boolean description: | The flag indicating whether Authlete generates access tokens for external attachments and embeds them in ID tokens and userinfo responses. authorityHints: type: array items: type: string description: | Identifiers of entities that can issue entity statements for this service. This property corresponds to the `authority_hints` property that appears in a self-signed entity statement that is defined in OpenID Connect Federation 1.0. federationEnabled: type: boolean description: | flag indicating whether this service supports OpenID Connect Federation 1 federationJwks: type: string description: | JWK Set document containing keys that are used to sign (1) self-signed entity statement of this service and (2) the response from `signed_jwks_uri`. federationSignatureKeyId: type: string description: | A key ID to identify a JWK used to sign the entity configuration and the signed JWK Set. federationConfigurationDuration: type: integer description: | The duration of the entity configuration in seconds. federationRegistrationEndpoint: type: string description: | The URI of the federation registration endpoint. This property corresponds to the `federation_registration_endpoint` server metadata that is defined in OpenID Connect Federation 1.0. organizationName: type: string description: | The human-readable name representing the organization that operates this service. This property corresponds to the `organization_name` server metadata that is defined in OpenID Connect Federation 1.0. predefinedTransformedClaims: type: string description: | The transformed claims predefined by this service in JSON format. This property corresponds to the `transformed_claims_predefined` server metadata. refreshTokenIdempotent: type: boolean description: | flag indicating whether refresh token requests with the same refresh token can be made multiple times in quick succession and they can obtain the same renewed refresh token within the short period. signedJwksUri: type: string description: | The URI of the endpoint that returns this service's JWK Set document in the JWT format. This property corresponds to the `signed_jwks_uri` server metadata defined in OpenID Connect Federation 1.0. supportedAttachments: type: array items: $ref: '#/components/schemas/attachment_type' description: | Supported attachment types. This property corresponds to the {@code attachments_supported} server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0. supportedDigestAlgorithms: type: array items: type: string description: | Supported algorithms used to compute digest values of external attachments. This property corresponds to the `digest_algorithms_supported` server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0. supportedDocuments: type: array items: type: string description: | Document types supported by this service. This property corresponds to the `documents_supported` server metadata. supportedDocumentsMethods: type: array items: type: string description: | validation and verification processes supported by this service. This property corresponds to the `documents_methods_supported` server metadata. The third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) renamed the `id_documents_verification_methods_supported` server metadata to `documents_methods_supported`. supportedDocumentsValidationMethods: type: array items: type: string description: | Document validation methods supported by this service. This property corresponds to the `documents_validation_methods_supported` server metadata which was added by the third implementer's draft of supportedDocumentsVerificationMethods: type: array items: type: string description: | Document verification methods supported by this service. This property corresponds to the `documents_verification_methods_supported` server metadata which was added by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) supportedElectronicRecords: type: array items: type: string description: | Electronic record types supported by this service. This property corresponds to the `electronic_records_supported` server metadata which was added by the third implementer's draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) supportedClientRegistrationTypes: type: array items: $ref: '#/components/schemas/client_registration_type' tokenExchangeByIdentifiableClientsOnly: type: boolean description: | The flag indicating whether to prohibit unidentifiable clients from making token exchange requests. tokenExchangeByConfidentialClientsOnly: type: boolean description: | The flag indicating whether to prohibit public clients from making token exchange requests. tokenExchangeByPermittedClientsOnly: type: boolean description: | The flag indicating whether to prohibit clients that have no explicit permission from making token exchange requests. tokenExchangeEncryptedJwtRejected: type: boolean description: | The flag indicating whether to reject token exchange requests which use encrypted JWTs as input tokens. tokenExchangeUnsignedJwtRejected: type: boolean description: | The flag indicating whether to reject token exchange requests which use unsigned JWTs as input tokens. jwtGrantByIdentifiableClientsOnly: type: boolean description: | The flag indicating whether to prohibit unidentifiable clients from using the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". jwtGrantEncryptedJwtRejected: type: boolean description: | The flag indicating whether to reject token requests that use an encrypted JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". jwtGrantUnsignedJwtRejected: type: boolean description: | The flag indicating whether to reject token requests that use an unsigned JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". dcrDuplicateSoftwareIdBlocked: type: boolean description: | The flag indicating whether to block DCR (Dynamic Client Registration) requests whose "software_id" has already been used previously. trustAnchors: type: array items: $ref: '#/components/schemas/trust_anchor' description: | The trust anchors that are referenced when this service resolves trust chains of relying parties. If this property is empty, client registration fails regardless of whether its type is `automatic` or `explicit`. It means that OpenID Connect Federation 1.0 does not work. openidDroppedOnRefreshWithoutOfflineAccess: type: boolean description: | The flag indicating whether the openid scope should be dropped from scopes list assigned to access token issued when a refresh token grant is used. supportedDocumentsCheckMethods: type: array items: type: string description: | Supported document check methods. This property corresponds to the `documents_check_methods_supported` server metadata which was added by the fourth implementer's draft of OpenID Connect for Identity Assurance 1.0. rsResponseSigned: type: boolean description: | The flag indicating whether this service signs responses from the resource server. cnonceDuration: type: integer format: int64 description: | The duration of `c_nonce`. dpopNonceRequired: type: boolean description: | Whether to require DPoP proof JWTs to include the `nonce` claim whenever they are presented. verifiableCredentialsEnabled: type: boolean description: | Get the flag indicating whether the feature of Verifiable Credentials for this service is enabled or not. credentialJwksUri: type: string description: | The URL at which the JWK Set document of the credential issuer is exposed. credentialOfferDuration: type: integer format: int64 description: | The default duration of credential offers in seconds. dpopNonceDuration: type: integer format: int64 description: | The duration of nonce values for DPoP proof JWTs in seconds. preAuthorizedGrantAnonymousAccessSupported: type: boolean description: | The flag indicating whether token requests using the pre-authorized code grant flow by unidentifiable clients are allowed. credentialTransactionDuration: type: integer format: int64 description: | The duration of transaction ID in seconds that may be issued as a result of a credential request or a batch credential request. introspectionSignatureKeyId: type: string description: | The key ID of the key for signing introspection responses. resourceSignatureKeyId: type: string description: | The key ID of the key for signing introspection responses. userPinLength: type: integer format: int32 description: | The default length of user PINs. supportedPromptValues: type: array items: $ref: '#/components/schemas/prompt' description: | The supported `prompt` values. idTokenReissuable: type: boolean description: | The flag indicating whether to enable the feature of ID token reissuance in the refresh token flow. credentialJwks: type: string description: | The JWK Set document containing private keys that are used to sign verifiable credentials. fapiModes: type: array items: $ref: '#/components/schemas/fapi_mode' description: | FAPI modes for this service. When the value of this property is not `null`, Authlete always processes requests to this service based on the specified FAPI modes if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service. For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete always processes requests to this service based on "Financial-grade API Security Profile 1.0 - Part 2: Advanced" if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service. credentialDuration: type: integer format: int64 description: | The default duration of verifiable credentials in seconds. credentialIssuerMetadata: $ref: '#/components/schemas/credential_issuer_metadata' idTokenAudType: type: string description: | The type of the `aud` claim in ID tokens. nativeSsoSupported: type: boolean description: | Flag that enables the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (β€œNative SSO”). When this property is **not** `true`, Native SSO specific parameters are ignored or treated as errors. For example: * The `device_sso` scope has no special meaning (Authlete does not embed the `sid` claim in ID tokens). * The `urn:openid:params:token-type:device-secret` token type is treated as unknown and results in an error. When set to `true`, the server metadata advertises `"native_sso_supported": true`. See [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) and [RFC 8414 Β§2](https://www.rfc-editor.org/rfc/rfc8414.html#section-2) for background. Native SSO is available in Authlete 3.0 and later. oid4vciVersion: type: string description: | Version of the [OpenID for Verifiable Credential Issuance](https://www.authlete.com/developers/oid4vci/) (OID4VCI) specification to support. Accepted values are: * `null` or `"1.0-ID1"` β†’ Implementer’s Draft 1. * `"1.0"` or `"1.0-Final"` β†’ Final 1.0 specification. Choose the value that matches the OID4VCI behaviour your service should expose. See the OID4VCI documentation for details. cimdMetadataPolicyEnabled: type: boolean description: | Flag that controls whether the CIMD metadata policy is applied to client metadata obtained through the Client ID Metadata Document (CIMD) mechanism. clientIdMetadataDocumentSupported: type: boolean description: | Indicates whether the Client ID Metadata Document (CIMD) mechanism is supported. When `true`, the service will attempt to retrieve client metadata via CIMD where applicable. cimdAllowlistEnabled: type: boolean description: | Enables the allowlist for CIMD. When `true`, only CIMD endpoints that are on the allowlist are used. cimdAllowlist: type: array items: type: string description: | The allowlist of CIMD endpoints (hosts/URIs) that may be used when retrieving client metadata via Client ID Metadata Documents. cimdAlwaysRetrieved: type: boolean description: | If `true`, CIMD retrieval is always attempted for clients, regardless of other conditions. cimdHttpPermitted: type: boolean description: | Allows CIMD retrieval over plain HTTP. When `false`, only HTTPS CIMD endpoints are allowed. cimdQueryPermitted: type: boolean description: | Allows the use of query parameters when retrieving CIMD metadata. When `false`, query parameters are disallowed for CIMD requests. cimdMetadataPolicy: type: string description: | The metadata policy applied to client metadata obtained through the CIMD mechanism. The value must follow the metadata policy grammar defined in [OpenID Federation 1.0 Β§6.1 Metadata Policy](https://openid.net/specs/openid-federation-1_0.html#name-metadata-policy). httpAliasProhibited: type: boolean description: | When `true`, client ID aliases starting with `https://` or `http://` are prohibited. attestationChallengeTimeWindow: type: integer format: int64 description: | The time window of attestation challenges in seconds. This is used for OAuth 2.0 Attestation-Based Client Authentication. sns_credentials: type: object properties: sns: type: string description: SNS. apiKey: type: string description: API key. apiSecret: type: string description: API secret. sns: type: string enum: - FACEBOOK subject_type: type: string description: | The subject type that the client application requests. Details about the subject type are described in [OpenID Connect Core 1.0, 8. Subjct Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes). This property corresponds to `subject_type` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). enum: - PUBLIC - PAIRWISE tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. user_code_charset: type: string description: | The character set for end-user verification codes (`user_code`) for Device Flow. enum: - BASE20 - NUMERIC hsk: type: object description: | Holds information about a key managed in an HSM (Hardware Security Module) properties: kty: type: string description: | The key type (EC or RSA) use: type: string description: | Get the use of the key on the HSM. When the key use is "sig" (signature), the private key on the HSM is used to sign data and the corresponding public key is used to verify the signature. When the key use is "enc" (encryption), the private key on the HSM is used to decrypt encrypted data which have been encrypted with the corresponding public key kid: type: string description: | Key ID for the key on the HSM. hsmName: type: string description: | The name of the HSM. The identifier for the HSM that sits behind the Authlete server. For example, "google". handle: type: string description: | The handle for the key on the HSM. A handle is a base64url-encoded 256-bit random value (43 letters) which is assigned by Authlete on the call of the /api/hsk/create API publicKey: type: string description: | The public key that corresponds to the key on the HSM. alg: type: string description: | The algorithm of the key on the HSM. When the key use is `"sig"`, the algorithm represents a signing algorithm such as `"ES256"`. When the key use is `"enc"`, the algorithm represents an encryption algorithm such as `"RSA-OAEP-256"`. credential_offer_info: type: object properties: identifier: type: string description: The identifier of the credential offer. credentialOffer: type: string description: The credential offer in the JSON format. credentialIssuer: type: string description: The identifier of the credential issuer. authorizationCodeGrantIncluded: type: boolean description: | The flag indicating whether the `authorization_code` object is included in the `grants` object. issuerStateIncluded: type: boolean description: | The flag indicating whether the `issuer_state` property is included in the `authorization_code` object in the `grants` object. issuerState: type: string description: | The value of the `issuer_state` property in the `authorization_code` object in the `grants` object. preAuthorizedCodeGrantIncluded: type: boolean description: | The flag indicating whether the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object is included in the `grants` object. preAuthorizedCode: type: string description: | The value of the `pre-authorized_code` property in the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object in the `grants` object. subject: type: string description: The subject associated with the credential offer. expiresAt: type: integer format: int64 description: The time at which the credential offer will expire. context: type: string description: The general-purpose arbitrary string. properties: type: array items: $ref: '#/components/schemas/property' description: Extra properties to associate with the credential offer. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. authTime: type: integer format: int64 description: | The time at which the user authentication was performed during the course of issuing the credential offer. acr: type: string description: | The Authentication Context Class Reference of the user authentication performed during the course of issuing the credential offer. credentialConfigurationIds: type: array items: type: string description: | The value of the `credential_configuration_ids` property of the credential offer. x-mint: metadata: description: "The value of the `credential_configuration_ids` property of the credential offer." content: | ``` { "credential_issuer": "...", "credential_configuration_ids": [ ... ], "grants": { ... } } ``` txCode: type: string description: | The transaction code. txCodeInputMode: type: string description: | The input mode of the transaction code. txCodeDescription: type: string description: | The description of the transaction code. credential_request_info: type: object properties: identifier: type: string description: The identifier of the credential offer. format: type: string description: The value of the format parameter in the credential request. bindingKey: type: string description: The binding key specified by the proof in the credential request. bindingKeys: type: array items: type: string description: The binding keys specified by the proofs in the credential request. details: type: string description: The details about the credential request. credential_issuance_order: type: object properties: requestIdentifier: type: string description: The identifier of a credential request. credentialPayload: type: string description: The additional payload that will be added into a credential to be issued. issuanceDeferred: type: boolean description: The flag indicating whether to defer credential issuance. credentialDuration: type: integer format: int64 description: The duration of a credential to be issued. signingKeyId: type: string description: | The key ID of a private key that should be used for signing a credential to be issued. credential_issuer_metadata: type: object properties: authorizationServers: type: array items: type: string description: | The identifiers of the authorization servers that the credential issuer relies on for authorization. This property corresponds to the authorization_servers metadata. When the credential issuer works as an authorization server for itself, this property should be omitted. credentialIssuer: type: string description: The identifier of a credential request. credentialEndpoint: type: string format: uri description: The URL of the credential endpoint of the credential issuer. batchCredentialEndpoint: type: string format: uri description: The URL of the batch credential endpoint of the credential issuer. deferredCredentialEndpoint: type: string description: The URL of the deferred credential endpoint of the credential issuer. credentialsSupported: type: string description: | A JSON object describing supported credential configurations. This property corresponds to the credential_configurations_supported metadata. Note: Due to a breaking change in December 2023, this was changed from a JSON array to a JSON object. credentialResponseEncryptionAlgValuesSupported: type: array items: type: string description: | The supported JWE `alg` algorithms for credential response encryption. This property corresponds to the `credential_response_encryption.alg_values_supported` metadata. credentialResponseEncryptionEncValuesSupported: type: array items: type: string description: | The supported JWE `enc` algorithms for credential response encryption. This property corresponds to the `credential_response_encryption.enc_values_supported` metadata. requireCredentialResponseEncryption: type: boolean description: | The boolean flag indicating whether credential response encryption is required. This property corresponds to the `credential_response_encryption.encryption_required metadata`. If this flag is `true`, every credential request to the credential issuer must include the `credential_response_encryption` property. verified_claims_validation_schema: type: string description: | The verified claims validation schema set. enum: - standard - standard+id_document attachment_type: type: string description: | Supported attachment types. This property corresponds to the `attachments_supported` server metadata which was added by the third implementer's draft of OpenID Connect for Identity Assurance 1.0. enum: - EMBEDDED - EXTERNAL client_registration_type: type: string description: | Values for the `client_registration_types` RP metadata and the `client_registration_types_supported` OP metadata that are defined in [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html). enum: - AUTOMATIC - EXPLICIT trust_anchor: type: object properties: entityId: type: string description: | the entity ID of the trust anchor jwks: type: string description: | the JWK Set document containing public keys of the trust anchor fapi_mode: type: string enum: - FAPI1_ADVANCED - FAPI1_BASELINE - FAPI2_MESSAGE_SIGNING_AUTH_REQ - FAPI2_MESSAGE_SIGNING_AUTH_RES - FAPI2_MESSAGE_SIGNING_INTROSPECTION_RES - FAPI2_SECURITY 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. service_get_list_response: type: object properties: start: type: integer format: int32 description: | Start index (inclusive) of the result set. The default value is 0. Must not be a negative number. end: type: integer format: int32 description: | Start index (inclusive) of the result set. The default value is 0. Must not be a negative number. totalCount: type: integer format: int32 description: | Total number of services owned by the service owner. This doesn't mean the number of services contained in the response. services: type: array items: $ref: '#/components/schemas/service' description: | An array of services. client_type: type: string description: | The client type, either `CONFIDENTIAL` or `PUBLIC`. See [RFC 6749, 2.1. Client Types](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) for details. enum: - PUBLIC - CONFIDENTIAL client_get_list_response: type: object properties: start: type: integer format: int32 description: | Start index (inclusive) of the result set of the query. end: type: integer format: int32 description: | End index (exclusive) of the result set of the query. totalCount: type: integer format: int32 description: | Total number of clients that belong to the service. This doesn't mean the number of clients contained in the response. clients: type: array items: $ref: '#/components/schemas/client' description: | An array of clients. client_flag_update_request: type: object required: - clientLocked properties: clientLocked: type: boolean description: | The flag value to be set client_flag_update_response: type: object required: - resultCode - resultMessage 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. client_secret_refresh_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. newClientSecret: type: string description: | The new client secret. oldClientSecret: type: string description: | The old client secret. client_secret_update_request: type: object required: - clientSecret properties: clientSecret: type: string description: | The new value of the client secret. Valid characters for a client secret are `A-Z`, `a-z`, `0-9`, `-`, and `_`. The maximum length of a client secret is 86. client_secret_update_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. newClientSecret: type: string description: | The new client secret. oldClientSecret: type: string description: | The old client secret. client_limited: type: object properties: number: type: integer format: int32 readOnly: true description: | The sequential number of the client. The value of this property is assigned by Authlete. clientName: type: string description: | The name of the client application. This property corresponds to `client_name` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). clientNames: type: array items: $ref: '#/components/schemas/tagged_value' description: | Client names with language tags. If the client application has different names for different languages, this property can be used to register the names. description: type: string description: The description about the client application. descriptions: type: array items: $ref: '#/components/schemas/tagged_value' description: | Descriptions about the client application with language tags. If the client application has different descriptions for different languages, this property can be used to register the descriptions. clientId: type: integer format: int64 readOnly: true description: The client identifier used in Authlete API calls. The value of this property is assigned by Authlete. clientIdAlias: type: string description: | The value of the client's `client_id` property used in OAuth and OpenID Connect calls. By default, this is a string version of the `clientId` property. clientIdAliasEnabled: type: boolean description: Deprecated. Always set to `true`. clientType: $ref: '#/components/schemas/client_type' client_authorization_get_list_response: type: object properties: start: type: integer format: int32 description: | Start index of search results (inclusive). end: type: integer format: int32 description: | End index of search results (exclusive). developer: type: string description: | Unique ID of a client developer. subject: type: string description: | Unique user ID of an end-user. totalCount: type: integer format: int32 description: | Unique ID of a client developer. clients: type: array items: $ref: '#/components/schemas/client_limited' description: | An array of clients. client_authorization_get_list_request: type: object properties: subject: type: string description: Unique user ID of an end-user. developer: type: string description: Unique ID of a client developer. start: type: integer format: int32 description: Start index of search results (inclusive). end: type: integer format: int32 description: End index of search results (exclusive). required: - subject client_authorization_update_request: type: object required: - subject properties: subject: type: string description: | The subject (= unique identifier) of the end-user who has granted authorization to the client application. scopes: type: array items: type: string description: | An array of new scopes. Optional. If a non-null value is given, the new scopes are set to all existing access tokens. If an API call is made using `"Content-Type: application/x-www-form-urlencoded"`, scope names listed in this request parameter should be delimited by spaces (after form encoding, spaces are converted to `+`). client_authorization_update_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. client_authorization_delete_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. serviceApiKey: type: integer format: int64 description: A short message which explains the result of the API call. clientId: type: integer format: int64 description: Get the client ID. subject: type: string description: | Get the subject (= unique identifier) of the user who has granted authorization to the client. latestGrantedScopes: type: array items: type: string description: | Get the scopes granted to the client application by the last authorization process by the user (who is identified by the subject). mergedGrantedScopes: type: array items: type: string description: | Get the scopes granted to the client application by all the past authorization processes. Note that revoked scopes are not included. modifiedAt: type: integer format: int64 description: | Get the timestamp in milliseconds since Unix epoch at which this record was modified. client_granted_scopes_delete_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. cimd_options: type: object description: | Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. properties: alwaysRetrieved: type: boolean description: | Whether to always retrieve client metadata in the CIMD context regardless of the cache's validity. Under normal circumstances, client metadata retrieved from the location referenced by the client ID is stored in the database with an expiration time calculated using HTTP caching mechanisms (see [RFC 9111 HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that expiration time is reached, Authlete does not attempt to retrieve the client metadata again. When this flag is set to `true`, Authlete retrieves the client metadata regardless of the cache's validity. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdAlwaysRetrieved`). This flag is effective only when the service supports CIMD (see `Service.clientIdMetadataDocumentSupported`) and CIMD is actually used to resolve client metadata. For example, if the client ID in a request does not appear to be a valid URI, CIMD will not be used even if the service is configured to support it. In such cases, this flag has no effect. Client metadata retrieval is performed only in the initiating request of an authorization flow, and not in any subsequent requests. For example, in the authorization code flow, metadata may be retrieved during the authorization request, but not during the subsequent token request. In contrast, in the client credentials flow, metadata retrieval may occur because the token request itself is the initiating request in the flow. httpPermitted: type: boolean description: | Whether to allow the `http` scheme in client IDs in the CIMD context. The specification requires the `https` scheme, but if this flag is set to `true`, Authlete also allows the `http` scheme. The main purpose of this option is to make development easier for developers who run CIMD-enabled servers and a web server publishing client metadata on their local machines without TLS. Given this purpose, it is not recommended to enable this option in production environments unless an allowlist is used (see `Service.cimdAllowlistEnabled`). If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdHttpPermitted`). queryPermitted: type: boolean description: | Whether to allow a query component in client IDs in the CIMD context. Although the specification states that a client ID "SHOULD NOT include a query string component," it does technically allow it. However, query components are prone to misuse. Therefore, Authlete does not allow them by default. Setting this flag to `true` relaxes that restriction. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdQueryPermitted`). authorization_request: type: object required: - parameters properties: parameters: type: string description: | OAuth 2.0 authorization request parameters which are the request parameters that the OAuth 2.0 authorization endpoint of the authorization server implementation received from the client application. The value of parameters is either (1) the entire query string when the HTTP method of the request from the client application is `GET` or (2) the entire entity body (which is formatted in `application/x-www-form-urlencoded`) when the HTTP method of the request from the client application is `POST`. context: type: string description: | The arbitrary text to be attached to the ticket that will be issued from the `/auth/authorization` API. The text can be retrieved later by the `/auth/authorization/ticket/info` API and can be updated by the `/auth/authorization/ticket/update` API. The text will be compressed and encrypted when it is saved in the Authlete database. cimdOptions: $ref: '#/components/schemas/cimd_options' description: | Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. client_limited_authorization: type: object properties: number: type: integer format: int32 readOnly: true description: | The sequential number of the client. The value of this property is assigned by Authlete. clientName: type: string description: | The name of the client application. This property corresponds to `client_name` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). clientNames: type: array items: $ref: '#/components/schemas/tagged_value' description: | Client names with language tags. If the client application has different names for different languages, this property can be used to register the names. description: type: string description: The description about the client application. descriptions: type: array items: $ref: '#/components/schemas/tagged_value' description: | Descriptions about the client application with language tags. If the client application has different descriptions for different languages, this property can be used to register the descriptions. clientId: type: integer format: int64 readOnly: true description: The client identifier used in Authlete API calls. The value of this property is assigned by Authlete. clientIdAlias: type: string description: | The value of the client's `client_id` property used in OAuth and OpenID Connect calls. By default, this is a string version of the `clientId` property. clientIdAliasEnabled: type: boolean description: Deprecated. Always set to `true`. clientType: $ref: '#/components/schemas/client_type' logoUri: type: string description: | The URL pointing to the logo image of the client application. This property corresponds to `logo_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). logoUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | Logo image URLs with language tags. If the client application has different logo images for different languages, this property can be used to register URLs of the images. tosUri: type: string description: | The URL pointing to the "Terms Of Service" page. This property corresponds to `tos_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). tosUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | URLs of "Terms Of Service" pages with language tags. If the client application has different "Terms Of Service" pages for different languages, this property can be used to register the URLs. policyUri: type: string description: | The URL pointing to the page which describes the policy as to how end-user's profile data is used. This property corresponds to `policy_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). policyUris: type: array items: $ref: '#/components/schemas/tagged_value' description: | URLs of policy pages with language tags. If the client application has different policy pages for different languages, this property can be used to register the URLs. serviceNumber: type: integer format: int32 readOnly: true description: | The sequential number of the service of the client application. The value of this property is assigned by Authlete. defaultMaxAge: type: integer format: int32 description: | The default maximum authentication age in seconds. This value is used when an authorization request from the client application does not have `max_age` request parameter. This property corresponds to `default_max_age` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). authTimeRequired: type: boolean description: | The flag to indicate whether this client requires `auth_time` claim to be embedded in the ID token. This property corresponds to `require_auth_time` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). createdAt: type: integer format: int64 readOnly: true description: The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01). modifiedAt: type: integer format: int64 readOnly: true description: The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). tlsClientCertificateBoundAccessTokens: type: boolean description: | The flag to indicate whether this client use TLS client certificate bound access tokens. bcUserCodeRequired: type: boolean description: | The boolean flag to indicate whether a user code is required when this client makes a backchannel authentication request. This property corresponds to the `backchannel_user_code_parameter` metadata. dynamicallyRegistered: type: boolean readOnly: true description: | The flag to indicate whether this client has been registered dynamically. For more details, see [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). parRequired: type: boolean description: | The flag to indicate whether this client is required to use the pushed authorization request endpoint. This property corresponds to the `require_pushed_authorization_requests` client metadata defined in "OAuth 2.0 Pushed Authorization Requests". requestObjectRequired: type: boolean description: | The flag to indicate whether authorization requests from this client are always required to utilize a request object by using either `request` or `request_uri` request parameter. If this flag is set to `true` and the service's `traditionalRequestObjectProcessingApplied` is set to `false`, authorization requests from this client are processed as if `require_signed_request_object` client metadata of this client is `true`. The metadata is defined in "JAR (JWT Secured Authorization Request)". frontChannelRequestObjectEncryptionRequired: type: boolean description: | The flag indicating whether encryption of request object is required when the request object is passed through the front channel. x-mint: metadata: description: "The flag indicating whether encryption of request object is required when the request object is passed through the front channel." content: | This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/). Unecrypted request objects are accepted at the endpoint even if this flag is `true`. This flag does not indicate whether a request object is always required. There is a different flag, `requestObjectRequired`, for the purpose. Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` flag of the service is `true`. requestObjectEncryptionAlgMatchRequired: type: boolean description: | The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. x-mint: metadata: description: "The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata." content: | The `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_alg > > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects. The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present." The property that represents the client metadata is `requestEncryptionAlg`. See the description of `requestEncryptionAlg` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired` flag of the service is `true`. requestObjectEncryptionEncMatchRequired: type: boolean description: | The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. x-mint: metadata: description: "The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata." content: | The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_enc > > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided. The property that represents the client metadata is `requestEncryptionEnc`. See the description of `requestEncryptionEnc` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired` flag of the service is `true`. singleAccessTokenPerSubject: type: boolean description: | If `Enabled` is selected, an attempt to issue a new access token invalidates existing access tokens that are associated with the same combination of subject and client. Note that, however, attempts by Client Credentials Flow do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user's subject. Even if `Disabled` is selected here, single access token per subject is effective if `singleAccessTokenPerSubject` of the `Service` this client belongs to is Enabled. pkceRequired: type: boolean description: | The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow. If `true`, `code_challenge` request parameter is always required for authorization requests using Authorization Code Flow. See [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients) for details about `code_challenge` request parameter. pkceS256Required: type: boolean description: | The flag to indicate whether `S256` is always required as the code challenge method whenever [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636) is used. If this flag is set to `true`, `code_challenge_method=S256` must be included in the authorization request whenever it includes the `code_challenge` request parameter. Neither omission of the `code_challenge_method` request parameter nor use of plain (`code_challenge_method=plain`) is allowed. rsRequestSigned: type: boolean description: | The flag indicating whether this service signs responses from the resource server. dpopRequired: type: boolean description: | If the DPoP is required for this client locked: type: boolean description: | The flag which indicates whether this client is locked. mtlsEndpointAliasesUsed: type: boolean description: | The flag indicating whether the client intends to prefer mutual TLS endpoints over non-MTLS endpoints. This property corresponds to the `use_mtls_endpoint_aliases` client metadata that is defined in [FAPI 2.0 Security Profile, 8.1.1. use_mtls_endpoint_aliases](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-8.1.1). inScopeForTokenMigration: type: boolean description: | The flag indicating whether this client is in scope for token migration operations. trustChainExpiresAt: type: integer format: int64 description: | the expiration time of the trust chain that was used when this client was registered or updated by the mechanism defined in OpenID Connect Federation 1.0. The value is represented as milliseconds elapsed since the Unix epoch (1970-01-01). trustChainUpdatedAt: type: integer format: int64 description: | the time at which the trust chain was updated by the mechanism defined in OpenID Connect Federation 1.0 automaticallyRegistered: type: boolean description: | The flag indicating whether this client was registered by the "automatic" client registration of OIDC Federation. explicitlyRegistered: type: boolean description: | The flag indicating whether this client was registered by the "explicit" client registration of OIDC Federation. credentialResponseEncryptionRequired: type: boolean description: True if credential responses to this client must be always encrypted. metadataDocumentLocation: type: string format: uri description: | Location of the Client ID Metadata Document that was used for this client. This property is set when client metadata was retrieved via the OAuth Client ID Metadata Document (CIMD) mechanism. metadataDocumentExpiresAt: type: integer format: int64 description: | Expiration time of the metadata document (UNIX time in milliseconds). metadataDocumentUpdatedAt: type: integer format: int64 description: | Last-updated time of the metadata document (UNIX time in milliseconds). discoveredByMetadataDocument: type: boolean description: | Indicates whether this client was discovered via a Client ID Metadata Document. clientSource: type: string description: | Source of this client record. enum: - DYNAMIC_REGISTRATION - AUTOMATIC_REGISTRATION - EXPLICIT_REGISTRATION - METADATA_DOCUMENT - STATIC_REGISTRATION entityId: type: string description: | the entity ID of this client. grant_management_action: type: string description: | The grant management action of the device authorization request. The `grant_management_action` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). enum: - CREATE - QUERY - REPLACE - REVOKE - MERGE grant_scope: type: object properties: scope: type: string description: | Space-delimited scopes. resource: type: array items: type: string description: | List of resource indicators. grant: type: object properties: scopes: type: array items: $ref: '#/components/schemas/grant_scope' claims: type: array items: type: string description: | The claims associated with the Grant. authorizationDetails: $ref: '#/components/schemas/authz_details' 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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - LOCATION - FORM - NO_INTERACTION - INTERACTION description: The next action that the authorization server implementation should take. client: $ref: '#/components/schemas/client_limited_authorization' display: $ref: '#/components/schemas/display' maxAge: type: integer format: int32 description: | The maximum authentication age. This value comes from `max_age` request parameter, or `defaultMaxAge` configuration parameter of the client application when the authorization request does not contain `max_age` request parameter. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), max_age" for `max_age` request parameter, and see "[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), default_max_age" for `defaultMaxAge` configuration parameter. service: $ref: '#/components/schemas/service' scopes: type: array items: $ref: '#/components/schemas/scope' description: | The scopes that the client application requests. This value comes from `scope` request parameter. If the request does not contain `scope` parameter, this parameter is a list of scopes which are registered as default. If the authorization request does not have `scope` request parameter and the service has not registered any default scope, the value of this parameter is `null`. It is ensured that scopes listed by this parameters are contained in the list of supported scopes which are specified by `supportedScopes` configuration parameter of the service. Unsupported scopes in the authorization request do not cause an error and are just ignored. OpenID Connect defines some scope names which need to be treated specially. The table below lists the special scope names. | Name | Description | | --- | --- | | `openid` | This scope must be contained in `scope` request parameter to promote an OAuth 2.0 authorization request to an OpenID Connect request. It is described in "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), scope". | | `profile` | This scope is used to request some claims to be embedded in the ID token. The claims are `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated_at`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | | `email` | This scope is used to request some claims to be embedded in the ID token. The claims are `email` and `email_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | | `address` | This scope is used to request `address` claim to be embedded in the ID token. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). The format of `address` claim is not a simple string. It is described in [OpenID Connect Core 1.0, 5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim). | | `phone` | This scope is used to request some claims to be embedded in the ID token. The claims are `phone_number` and `phone_number_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). | | `offline_access` | The following is an excerpt about this scope from [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess). > This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the end-user's userinfo endpoint even when the end-user is not present (not logged in). | Note that, if `response_type` request parameter does not contain code, `offline_acccess` scope is removed from this list even when scope request parameter contains `offline_access`. This behavior is a requirement written in [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess). uiLocales: type: array items: type: string description: | The locales that the client application presented as candidates to be used for UI. This value comes from `ui_locales` request parameter. The format of `ui_locales` is a space-separated list of language tag values defined in [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), ui_locales" for details. It is ensured that locales listed by this parameters are contained in the list of supported UI locales which are specified by `supportedUiLocales` configuration parameter of the service. Unsupported UI locales in the authorization request do not cause an error and are just ignored. claimsLocales: type: array items: type: string description: | End-user's preferred languages and scripts for claims. This value comes from `claims_locales` request parameter. The format of `claims_locales` is a space-separated list of language tag values defined in [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). See "[OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)" for details. It is ensured that locales listed by this parameters are contained in the list of supported claim locales which are specified by `supportedClaimsLocales` configuration parameter of the service. Unsupported claim locales in the authorization request do not cause an error and are just ignored. claims: type: array items: type: string description: | The list of claims that the client application requests to be embedded in the ID token. The value comes from (1) `id_token` in `claims` request parameter [1] and/or (2) special scopes (`profile`, `email`, `address` and `phone`) which are expanded to claims. See [OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter) for `claims` request parameter, and see [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for the special scopes. acrEssential: type: boolean description: | This boolean value indicates whether the authentication of the end-user must be one of the ACRs (Authentication Context Class References) listed in `acrs` parameter. This parameter becomes `true` only when (1) the authorization request contains `claims` request parameter and (2) `acr` claim is in it, and (3) `essential` property of the `acr` claim is `true`. See [OpenID Connect Core 1.0, 5.5.1.1. Requesting the "acr" Claim](https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics) for details. clientIdAliasUsed: type: boolean description: | `true` if the value of the `client_id` request parameter included in the authorization request is the client ID alias. `false` if the value is the original numeric client ID. acrs: type: array items: type: string description: | The list of ACRs (Authentication Context Class References) one of which the client application requests to be satisfied for the authentication of the end-user. This value comes from `acr_values` request parameter or `defaultAcrs` configuration parameter of the client application. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), acr_values" for `acr_values` request parameter, and see "[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), default_acr_values" for `defaultAcrs` configuration parameter. subject: type: string description: | The subject (= unique user ID managed by the authorization server implementation) that the client application expects to grant authorization. The value comes from `sub` claim in `claims` request parameter. loginHint: type: string description: A hint about the login identifier of the end-user. The value comes from `login_hint` request parameter. prompts: type: array items: $ref: '#/components/schemas/prompt' description: The list of values of prompt request parameter. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), prompt" for prompt request parameter. lowestPrompt: $ref: '#/components/schemas/prompt' requestObjectPayload: type: string description: | The payload part of the request object. The value of this proprty is `null` if the authorization request does not include a request object. idTokenClaims: type: string description: | The value of the `id_token` property in the claims request parameter or in the claims property in a request object. x-mint: metadata: description: "The value of the `id_token` property in the claims request parameter or in the claims property in a request object." content: | A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. ```json { "userinfo": { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } } ``` This value of this property is the value of the `id_token` property in JSON format. For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. ```json { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } ``` Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, this property holds the former value. userInfoClaims: type: string description: | The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object. x-mint: metadata: description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object." content: | A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. In both the cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. ```json { "userinfo": { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } } ```` The value of this property is the value of the `userinfo` property in JSON format. For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. ```json { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null } ``` Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, the value of this property holds the former value. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' purpose: type: string description: | The `purpose` request parameter is defined in [9. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#name-transaction-specific-purpos) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) as follows: > purpose: OPTIONAL. String describing the purpose for obtaining certain user data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. ticket: type: string description: | A ticket issued by Authlete to the service implementation. This is needed when the service implementation calls either `/auth/authorization/fail` API or `/auth/authorization/issue` API. dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: | The dynamic scopes which the client application requested by the scope request parameter. gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. grant: $ref: '#/components/schemas/grant' grantSubject: type: string description: | The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant. requestedClaimsForTx: type: array items: type: string description: | Names of claims that are requested indirectly by *"transformed claims"*. A client application can request *"transformed claims"* by adding names of transformed claims in the `claims` request parameter. The following is an example of the `claims` request parameter that requests a predefined transformed claim named `18_or_over` and a transformed claim named `nationality_usa` to be embedded in the response from the userinfo endpoint. ```json { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "userinfo": { "::18_or_over": null, ":nationality_usa": null } } ``` The example above assumes that a transformed claim named `18_or_over` is predefined by the authorization server like below. ```json { "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } } ``` In the example, the `nationalities` claim is requested indirectly by the `nationality_usa` transformed claim. Likewise, the `birthdate` claim is requested indirectly by the `18_or_over` transformed claim. When the `claims` request parameter of an authorization request is like the example above, this `requestedClaimsForTx` property will hold the following value. ```json [ "birthdate", "nationalities" ] ``` It is expected that the authorization server implementation prepares values of the listed claims and passes them as the value of the `claimsForTx` request parameter when it calls the `/api/auth/userinfo/issue` API. The following is an example of the value of the `claimsForTx` request parameter. ```json { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] } ``` requestedVerifiedClaimsForTx: type: array items: type: array items: type: string description: | Names of verified claims that will be referenced when transformed claims are computed. transformedClaims: type: string description: | the value of the `transformed_claims` property in the `claims` request parameter of an authorization request or in the `claims` property in a request object. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. claimsAtUserInfo: type: array items: type: string description: | The list of claims that the client application requests to be embedded in userinfo responses. The value comes from the `"scope"` and `"claims"` request parameters of the original authorization request. credentialOfferInfo: $ref: '#/components/schemas/credential_offer_info' issuableCredentials: type: string description: | The information about the **issuable credentials** that can be obtained by presenting the access token that will be issued as a result of the authorization request. nativeSsoRequested: type: boolean description: | Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied: x-mint: metadata: description: "Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied:" content: | - The service supports Native SSO (see `nativeSsoSupported` property of Service). - The service supports the `openid` and `device_sso` scopes. - The client is allowed to request the `openid` and `device_sso` scopes. - The authorization request includes the `openid` and `device_sso` scopes. - The authorization request's `response_type` includes `code`. NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided to the `/auth/authorization/issue` API. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. authorization_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: | The ticket issued from Authlete `/auth/authorization` API. reason: type: string enum: - UNKNOWN - NOT_LOGGED_IN - MAX_AGE_NOT_SUPPORTED - EXCEEDS_MAX_AGE - DIFFERENT_SUBJECT - ACR_NOT_SATISFIED - DENIED - SERVER_ERROR - NOT_AUTHENTICATED - ACCOUNT_SELECTION_REQUIRED - CONSENT_REQUIRED - INTERACTION_REQUIRED - INVALID_TARGET description: | The reason of the failure of the authorization request. For more details, see [NO_INTERACTION] in the description of `/auth/authorization` API. description: type: string description: | The custom description about the authorization failure. authorization_fail_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - LOCATION - FORM description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. authorization_issue_request: type: object required: - ticket - subject properties: ticket: type: string description: | The ticket issued from Authlete `/auth/authorization` API. subject: type: string description: | The subject (= a user account managed by the service) who has granted authorization to the client application. authTime: type: integer format: int64 description: | The time when the authentication of the end-user occurred. Its value is the number of seconds from `1970-01-01`. acr: type: string description: The Authentication Context Class Reference performed for the end-user authentication. claims: type: string description: | The claims of the end-user (= pieces of information about the end-user) in JSON format. See [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) for details about the format. properties: type: array items: $ref: '#/components/schemas/property' description: Extra properties to associate with an access token and/or an authorization code. scopes: type: array items: type: string description: | Scopes to associate with an access token and/or an authorization code. If a non-empty string array is given, it replaces the scopes specified by the original authorization request. sub: type: string description: | The value of the `sub` claim to embed in an ID token. If this request parameter is `null` or empty, the value of the `subject` request parameter is used as the value of the `sub` claim. idtHeaderParams: type: string description: | JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request. claimsForTx: type: string description: | Claim key-value pairs that are used to compute transformed claims. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. authorizationDetails: $ref: '#/components/schemas/authz_details' jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. accessToken: type: string description: | The representation of an access token that may be issued as a result of the Authlete API call. accessTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. sessionId: type: string description: | The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. x-mint: metadata: description: "The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. \"Native SSO\"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`." content: | NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested` property with a value of `true`, the `sessionId` request parameter must be provided to the `/auth/authorization/issue` API. idTokenAudType: type: string description: | The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. verifiedClaimsForTx: type: array items: type: string description: | Values of verified claims requested indirectly by "transformed claims". x-mint: metadata: description: "Values of verified claims requested indirectly by \"transformed claims\"." content: | A client application may request "transformed claims". Each of transformed claims uses an existing claim as input. As a result, to compute the value of a transformed claim, the value of the referenced existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide values of existing claims for computation of transformed claims. A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response parameter which is a list of verified claims that are referenced indirectly by transformed claims (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` and pass them as the value of this `verifiedClaimsForTx` request parameter. The following is an example of the value of this request parameter. ``` [ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` property in the claims request parameter of an authorization request can be an array like below. ``` { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "id_token": { "verified_claims": [ { "verification": { "trust_framework": { "value": "gold" } }, "claims": { "::18_or_above": null } }, { "verification": { "trust_framework": { "value": "silver" } }, "claims": { ":nationality_usa": null } } ] } } ``` For the example above, the value of this `verifiedClaimsForTx` property should be an array of size 2 and look like below. The first element is JSON including claims which have been verified under the trust framework `"gold"`, and the second element is JSON including claims which have been verified under the trust framework `"silver"`. ``` [ "{\"birthdate\":\"1970-01-23\"}", "{\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` authorization_ticket_info: type: object properties: context: type: string description: | The arbitrary text attached to the ticket. authorization_issue_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - LOCATION - FORM description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. accessToken: type: string description: | The newly issued access token. Note that an access token is issued from an authorization endpoint only when `response_type` contains token. accessTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). accessTokenDuration: type: integer format: int64 description: | The duration of the newly issued access token in seconds. idToken: type: string description: | The newly issued ID token. Note that an ID token is issued from an authorization endpoint only when `response_type` contains `id_token`. authorizationCode: type: string description: | The newly issued authorization code. Note that an authorization code is issued only when `response_type` contains code. jwtAccessToken: type: string description: | The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this property is always set to `null`. ticketInfo: $ref: '#/components/schemas/authorization_ticket_info' description: | The information about the ticket. 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. 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. token_request: type: object required: - parameters properties: parameters: type: string description: | OAuth 2.0 token request parameters which are the request parameters that the OAuth 2.0 token endpoint of the authorization server implementation 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 token request from the client application. If the token endpoint of the authorization server implementation supports basic authentication as a means of client authentication, and the request from the client application contained its client ID in `Authorization` header, the value should be extracted and set to this parameter. clientSecret: type: string description: | The client secret extracted from `Authorization` header of the token request from the client application. If the token endpoint of the authorization server implementation supports basic authentication as a means of client authentication, and the request from the client application contained its client secret in `Authorization` header, the value should be extracted and set to this parameter. clientCertificate: type: string description: The client certificate from the MTLS of the token request 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. properties: type: array description: | Extra properties to associate with an access token. See [Extra Properties](https://www.authlete.com/developers/definitive_guide/extra_properties/) for details. items: $ref: '#/components/schemas/property' dpop: type: string description: | `DPoP` header presented by the client during the request to the token endpoint. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htm: type: string description: | HTTP method of the token request. This field is used to validate the `DPoP` header. In normal cases, the value is `POST`. When this parameter is omitted, `POST` is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htu: type: string description: | URL of the token endpoint. This field is used to validate the `DPoP` header. If this parameter is omitted, the `tokenEndpoint` property of the Service is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. accessToken: type: string description: | The representation of an access token that may be issued as a result of the Authlete API call. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. 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/). accessTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. refreshTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. 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 `/auth/token` API with this `dpopNonceRequired` parameter `true` will force the Authlete API to check whether the DPoP proof JWT includes the expected `nonce` value. cimdOptions: $ref: '#/components/schemas/cimd_options' description: | Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. token_type: type: string description: | The token type identifier used in OAuth 2.0 Token Exchange (RFC 8693). The API returns short codes (enum constant names) in response fields. enum: - JWT - ACCESS_TOKEN - REFRESH_TOKEN - ID_TOKEN - SAML1 - SAML2 - DEVICE_SECRET - DEVICE_CODE - TOKEN_EXCHANGE - JWT_BEARER token_info: type: object properties: clientId: type: integer description: The client id. clientIdAlias: type: string description: The alias of the client. clientIdAliasUsed: type: boolean description: Flag specifying if the alias was used to identify the client subject: type: string description: the resource owner unique id scopes: type: array items: $ref: '#/components/schemas/scope' description: The scopes granted on the token expiresAt: type: integer description: time which the token expires. properties: type: array description: Extra properties associated with the token items: $ref: '#/components/schemas/property' resources: type: array description: The array of the resources of the token. items: type: string authorizationDetails: $ref: '#/components/schemas/authorization_details_element' clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. token_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: - INTERNAL_SERVER_ERROR - INVALID_CLIENT - BAD_REQUEST - PASSWORD - OK - TOKEN_EXCHANGE - JWT_BEARER - NATIVE_SSO - ID_TOKEN_REISSUABLE description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. username: type: string description: | The value of `username` request parameter in the token request. The client application must specify username when it uses [Resource Owner Password Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3). In other words, when the value of `grant_type` request parameter is `password`, `username` request parameter must come along. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. password: type: string description: | The value of `password` request parameter in the token request. The client application must specify password when it uses [Resource Owner Password Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3). In other words, when the value of `grant_type` request parameter is `password`, `password` request parameter must come along. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. ticket: type: string description: | The ticket which is necessary to call Authlete's `/auth/token/fail` API or `/auth/token/issue` API. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. accessToken: type: string description: The newly issued access token. accessTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). accessTokenDuration: type: integer format: int64 description: The duration of the newly issued access token in seconds. refreshToken: type: string description: The newly issued refresh token. refreshTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). refreshTokenDuration: type: integer format: int64 description: The duration of the newly issued refresh token in seconds. idToken: type: string description: | The newly issued ID token. Note that an ID token is issued from a token endpoint only when the `response_type` request parameter of the authorization request to an authorization endpoint has contained `code` and the `scope` request parameter has contained `openid`. grantType: type: string description: The grant type of the token request. clientId: type: integer format: int64 description: The client ID. clientIdAlias: type: string description: | The client ID alias when the token request was made. If the client did not have an alias, this parameter is `null`. Also, if the token request was invalid and it failed to identify a client, this parameter is `null`. clientIdAliasUsed: type: boolean description: | The flag which indicates whether the client ID alias was used when the token request was made. `true` if the client ID alias was used when the token request was made. subject: type: string description: | The subject (= resource owner's ID) of the access token. Even if an access token has been issued by the call of `/api/auth/token` API, this parameter is `null` if the flow of the token request was [Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) (`grant_type=client_credentials`) because it means the access token is not associated with any specific end-user. scopes: type: array items: type: string description: The scopes covered by the access token. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. This parameter is `null` when no extra property is associated with the issued access token. jwtAccessToken: type: string description: | The newly issued access token in JWT format. If the authorization server is configured to issue JWT-based access tokens (= if the service's `accessTokenSignAlg` value is a non-null value), a JWT-based access token is issued along with the original random-string one. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details. accessTokenResources: type: array items: type: string description: | The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' additionalClaims: type: string description: | Additional claims to be embedded in an ID token. serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. clientAuthMethod: type: string description: | The client authentication method that was performed at the token endpoint. grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. audiences: type: array items: type: string description: | The audiences on the token exchange request requestedTokenType: $ref: '#/components/schemas/token_type' subjectToken: type: string subjectTokenType: $ref: '#/components/schemas/token_type' subjectTokenInfo: $ref: '#/components/schemas/token_info' actorToken: type: string actorTokenType: $ref: '#/components/schemas/token_type' actorTokenInfo: $ref: '#/components/schemas/token_info' assertion: type: string description: | For RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants previousRefreshTokenUsed: type: boolean description: | Indicate whether the previous refresh token that had been kept in the database for a short time was used clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. cnonceDuration: type: integer format: int64 description: | Duration of the `c_nonce` in seconds. 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. cnonce: type: string description: | Get the `c_nonce`. cnonceExpiresAt: type: integer format: int64 description: | Get the time at which the `c_nonce` expires in milliseconds since the Unix epoch (1970-01-01). requestedIdTokenClaims: type: array items: type: string description: | Get the names of the claims that the authorization request (which resulted in generation of the access token) requested to be embedded in ID tokens. refreshTokenScopes: type: array items: type: string description: | Scopes associated with the refresh token. sessionId: type: string description: | The session ID, which is the ID of the user's authentication session, associated with a newly created access token. deviceSecret: type: string description: | If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value. x-mint: metadata: description: "If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value." content: | If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or if its value is invalid, the authorization server must generate a new device secret and specify it in the deviceSecret parameter to the `/nativesso` API. The specified value is used as the value of the `device_secret` property in the token response. deviceSecretHash: type: string description: | The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API. x-mint: metadata: description: "The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API." content: | When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API generates the device secret hash by computing the SHA-256 hash of the device secret and encoding it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash` parameter is omitted. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. token_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: | The ticket issued from Authlete `/auth/token` API. reason: type: string enum: - UNKNOWN - INVALID_RESOURCE_OWNER_CREDENTIALS - INVALID_TARGET description: | The reason of the failure of the token request. token_fail_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. See description for details. token_issue_request: type: object required: - ticket - subject properties: ticket: type: string description: | The ticket issued from Authlete `/auth/token` API. subject: type: string description: | The subject (= unique identifier) of the authenticated user. properties: type: array items: $ref: '#/components/schemas/property' description: | Extra properties to associate with a newly created access token. Note that properties parameter is accepted only when `Content-Type` of the request is `application/json`, so don't use `application/x-www-form-urlencoded` if you want to specify properties. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. accessToken: type: string description: | The representation of an access token that may be issued as a result of the Authlete API call. accessTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. refreshTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. token_issue_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: - INTERNAL_SERVER_ERROR - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format is JSON. accessToken: type: string description: The newly issued access token. This parameter is a non-null value only when the value of `action` parameter is `OK`. accessTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). accessTokenDuration: type: integer format: int64 description: The duration of the newly issued access token in seconds. refreshToken: type: string description: | The refresh token. This parameter is a non-null value only when `action` is `OK` and the service supports the refresh token flow. If `refreshTokenKept` is set to `false`, a new refresh token is issued and the old refresh token used in the refresh token flow is invalidated. On the contrary, if `refreshTokenKept` is set to `true`, the refresh token itself is not refreshed. refreshTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). refreshTokenDuration: type: integer format: int64 description: The duration of the newly issued refresh token in seconds. clientId: type: integer format: int64 description: The client ID. clientIdAlias: type: string description: | The client ID alias. If the client did not have an alias, this parameter is `null`. clientIdAliasUsed: type: boolean description: | The flag which indicates whether the client ID alias was used when the token request was made. `true` if the client ID alias was used when the token request was made. subject: type: string description: | The subject (= resource owner's ID) of the access token. Even if an access token has been issued by calling `/api/auth/token` API, this parameter is `null` if the flow of the token request was [Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) (`grant_type=client_credentials`) because it means the access token is not associated with any specific end-user. scopes: type: array items: type: string description: The scopes covered by the access token. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. This parameter is `null` when no extra property is associated with the issued access token. jwtAccessToken: type: string description: | The newly issued access token in JWT format. If the authorization server is configured to issue JWT-based access tokens (= if the service's `accessTokenSignAlg` value is a non-null value), a JWT-based access token is issued along with the original random-string one. accessTokenResources: type: array items: type: string description: | The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. refreshTokenScopes: type: array items: type: string description: | The scopes associated with the refresh token. May be null. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. introspection_request: type: object required: - token properties: token: type: string description: An access token to introspect. scopes: type: array items: type: string description: | A string array listing names of scopes which the caller (= a protected resource endpoint of the service) requires. When the content type of the request from the service is `application/x-www-form-urlencoded`, the format of `scopes` is a space-separated list of scope names. If this parameter is a non-empty array and if it contains a scope which is not covered by the access token,`action=FORBIDDEN` with `error=insufficient_scope` is returned from Authlete. subject: type: string description: | A subject (= a user account managed by the service) whom the caller (= a protected resource endpoint of the service) requires. If this parameter is not `null` and if the value does not match the subject who is associated with the access token, `action=FORBIDDEN` with `error=invalid_request` is returned from Authlete. clientCertificate: type: string description: | Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method. dpop: type: string description: | `DPoP` header presented by the client during the request to the resource server. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htm: type: string description: | HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htu: type: string description: | URL of the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details. acrValues: type: array items: type: string description: | Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy. maxAge: type: integer format: int64 description: | The maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token. requiredComponents: type: array items: type: string description: | HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ]. uri: type: string description: | The full URL of the userinfo endpoint. message: type: string description: | The HTTP message body of the request, if present. headers: type: array items: $ref: '#/components/schemas/pair' description: | HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature. targetUri: type: string description: | The target URI of the resource request, including the query part, if any. x-mint: metadata: description: "The target URI of the resource request, including the query part, if any." content: | This parameter is used as the value of the @target-uri derived component for HTTP message signatures [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and `@query-param` are computed from this parameter. When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter represents the URL of the resource endpoint, which is identical to the target URI of the resource request as long as the request does not include a query component. Conversely, if the resource request includes a query component, the value of the `htu` parameter will not match the target URI, and in that case, the HTTP message signature verification will fail. If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is considered unavailable. If HTTP message signing requires the target-uri derived component or other derived components computed based on the target URI, the HTTP message signature verification will fail. dpopNonceRequired: type: boolean description: | The flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value. If this request parameter is set to `true` or if the service's `dpopNonceRequired` property is set to `true`, the `/auth/introspection` API checks if the DPoP proof JWT includes the expected `nonce` value. In this case, the response from the `/auth/introspection` API will include the `dpopNonce` response parameter, which should be used as the value of the DPoP-Nonce HTTP header. requestBodyContained: type: boolean description: | The flag indicating whether the resource request contains a request body. When the resource request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) if the resource request contains a request body. When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` is included in the signature base, if the FAPI profile applies to the resource request. introspection_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. clientId: type: integer format: int64 description: The client ID. clientIdAlias: type: string description: | The client ID alias when the token request was made. If the client did not have an alias, this parameter is `null`. Also, if the token request was invalid and it failed to identify a client, this parameter is `null`. clientIdAliasUsed: type: boolean description: | The flag which indicates whether the client ID alias was used when the token request was made. `true` if the client ID alias was used when the token request was made. expiresAt: type: integer format: int64 description: | The time at which the access token expires. The value is represented in milliseconds since the Unix epoch (1970-01-01). subject: type: string description: | The subject who is associated with the access token. The value of this property is `null` if the access token was issued using the flow of [Client Credentials Grant](tools.ietf.org/html/rfc6749#section-4.4). scopes: type: array items: type: string description: | The scopes covered by the access token. existent: type: boolean description: | `true` if the access token exists. usable: type: boolean description: | true` if the access token is usable (= exists and has not expired). sufficient: type: boolean description: | `true` if the access token exists. refreshable: type: boolean description: | `true` if the access token can be refreshed using the associated refresh token which had been issued along with the access token. `false` if the refresh token for the access token has expired or the access token has no associated refresh token. properties: type: array items: $ref: '#/components/schemas/property' description: The extra properties associated with the access token. certificateThumbprint: type: string description: | The client certificate thumbprint used to validate the access token. resources: type: array items: type: string description: | The target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object. See "Resource Indicators for OAuth 2.0" for details. accessTokenResources: type: array items: type: string description: | The target resources this proeprty holds may be the same as or different from the ones `resource` property holds. x-mint: metadata: description: "The target resources this proeprty holds may be the same as or different from the ones `resource` property holds." content: | In some flows, the initial request and the subsequent token request are sent to different endpoints. Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow. In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters. The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. scopeDetails: type: array items: $ref: '#/components/schemas/scope' description: | The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes. grantId: type: string description: | The value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. grant: $ref: '#/components/schemas/grant' forExternalAttachment: type: boolean description: | the flag which indicates whether the access token is for an external attachment. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. grantType: $ref: '#/components/schemas/grant_type' acr: type: string description: | The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token. authTime: type: integer format: int64 description: | The time when the user authentication was performed during the course of issuing the access token. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. forCredentialIssuance: type: boolean description: The flag indicating whether the token is for credential issuance. cnonce: type: string description: The c_nonce cnonceExpiresAt: type: integer format: int64 description: The time at which the `c_nonce` expires. issuableCredentials: type: string description: The credentials that can be obtained by presenting the access token. dpopNonce: type: string description: | The expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. responseSigningRequired: type: boolean description: | The flag indicating whether the HTTP response from the protected resource endpoint must include an HTTP message signature ([RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) in compliance with [FAPI 2.0 Message Signing](https://openid.bitbucket.io/fapi/fapi-2_0-message-signing.html). When this response parameter is `true`, the HTTP response from the protected resource endpoint must include the `Signature` and `Signature-Input` HTTP fields. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. standard_introspection_request: type: object required: - parameters properties: parameters: type: string description: | Request parameters which comply with the introspection request defined in "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in RFC 7662. The implementation of the introspection endpoint of your authorization server will receive an HTTP POST [[RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231)] 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: type: boolean description: | 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: type: string description: | 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: type: string description: | 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](https://www.rfc-editor.org/rfc/rfc9701.html#section-4)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)" for more details. introspectionSignAlg: type: string description: | The JWS `alg` algorithm for signing the introspection response. This parameter corresponds to `introspection_signed_response_alg` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". The default value is `RS256`. introspectionEncryptionAlg: type: string description: | The JWE `alg` algorithm for encrypting the introspection response. This parameter corresponds to `introspection_encrypted_response_alg` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". 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: type: string description: | The JWE `enc` algorithm for encrypting the introspection response. This parameter corresponds to `introspection_encrypted_response_enc` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". The default value is `A128CBC_HS256`. sharedKeyForSign: type: string description: | 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: type: string description: | 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: type: string description: | 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. standard_introspection_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - OK - JWT description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. revocation_request: type: object required: - parameters properties: parameters: type: string description: | OAuth 2.0 token revocation request parameters which are the request parameters that the OAuth 2.0 token revocation endpoint ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009)) of the authorization server implementation 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 revocation request from the client application. If the revocation endpoint of the authorization server implementation supports Basic Authentication as a means of client authentication, and the request from the client application contains its client ID in `Authorization` header, the value should be extracted and set to this parameter. clientSecret: type: string description: | The client secret extracted from `Authorization` header of the revocation request from the client application. If the revocation endpoint of the authorization server implementation supports basic authentication as a means of client authentication, and the request from the client application contained its client secret in `Authorization` header, the value should be extracted and set to this parameter. clientCertificate: type: string description: | The client certificate used in the TLS connection between the client application and the revocation endpoint. clientCertificatePath: type: array items: type: string description: | The certificate path presented by the client during client authentication. 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/). revocation_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: - INTERNAL_SERVER_ERROR - INVALID_CLIENT - BAD_REQUEST - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. userinfo_request: type: object required: - token properties: token: type: string description: | An access token. clientCertificate: type: string description: | Client certificate used in the TLS connection established between the client application and the userinfo endpoint. The value of this request parameter is referred to when the access token given to the userinfo endpoint was bound to a client certificate when it was issued. See [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens] (https://datatracker.ietf.org/doc/rfc8705/) for details about the specification of certificate-bound access tokens. dpop: type: string description: | `DPoP` header presented by the client during the request to the user info endpoint. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htm: type: string description: | HTTP method of the user info request. This field is used to validate the DPoP header. In normal cases, the value is either `GET` or `POST`. htu: type: string description: | URL of the user info endpoint. This field is used to validate the DPoP header. If this parameter is omitted, the `userInfoEndpoint` property of the service is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. uri: type: string description: | The full URL of the userinfo endpoint. message: type: string description: | The HTTP message body of the request, if present. headers: type: array items: $ref: '#/components/schemas/pair' description: | HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature. targetUri: type: string description: | The target URI of the userinfo request, including the query part, if any. x-mint: metadata: description: "The target URI of the userinfo request, including the query part, if any." content: | This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and `@query-param` are computed from this parameter. When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request. The only exception is when the access token is specified as a query parameter, as defined in [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750 states that this method "SHOULD NOT be used" unless other methods are not viable. If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint` property of the service is used as a fallback. dpopNonceRequired: type: boolean description: | The flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value. If this request parameter is set to `true` or if the service's `dpopNonceRequired` property is set to `true`, the `/auth/userinfo` API checks if the DPoP proof JWT includes the expected `nonce` value. In this case, the response from the `/auth/userinfo` API will include the `dpopNonce` response parameter, which should be used as the value of the DPoP-Nonce HTTP header. requestBodyContained: type: boolean description: | The flag indicating whether the userinfo request contains a request body. x-mint: metadata: description: "The flag indicating whether the userinfo request contains a request body." content: | When the userinfo request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) if the userinfo request contains a request body. When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` is included in the signature base, if the FAPI profile applies to the userinfo request. NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)). userinfo_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - OK description: The next action that the authorization server implementation should take. claims: type: array items: type: string description: | The list of claims that the client application requests to be embedded in the ID token. clientId: type: integer format: int64 description: | The ID of the client application which is associated with the access token. clientIdAlias: type: string description: | The client ID alias when the authorization request for the access token was made. clientIdAliasUsed: type: boolean description: | The flag which indicates whether the client ID alias was used when the authorization request for the access token was made. responseContent: type: string description: | The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. scopes: type: array items: type: string description: | The scopes covered by the access token. subject: type: string description: | The subject (= resource owner's ID). token: type: string description: | The access token that came along with the userinfo request. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. userInfoClaims: type: string description: | The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object. x-mint: metadata: description: "The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object." content: | A client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint. There are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples. In both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter). The following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties. ```json { "userinfo": { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null }, "id_token": { "auth_time": { "essential": true }, "acr": { "values": [ "urn:mace:incommon:iap:silver" ] } } } ```` The value of this property is the value of the `userinfo` property in JSON format. For example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following. ```json { "given_name": { "essential": true }, "nickname": null, "email": { "essential": true }, "email_verified": { "essential": true }, "picture": null, "http://example.info/claims/groups": null } ``` Note that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given, the value of this property holds the former value. serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. requestedClaimsForTx: type: array items: type: string description: | Get names of claims that are requested indirectly by *"transformed claims"*. A client application can request *"transformed claims"* by adding names of transformed claims in the `claims` request parameter. The following is an example of the `claims` request parameter that requests a predefined transformed claim named `18_or_over` and a transformed claim named `nationality_usa` to be embedded in the response from the userinfo endpoint. ```json { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "userinfo": { "::18_or_over": null, ":nationality_usa": null } } ``` The example above assumes that a transformed claim named `18_or_over` is predefined by the authorization server like below. ```json { "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } } ``` In the example, the `nationalities` claim is requested indirectly by the `nationality_usa` transformed claim. Likewise, the `birthdate` claim is requested indirectly by the `18_or_over` transformed claim. When the `claims` request parameter of an authorization request is like the example above, this `requestedClaimsForTx` property will hold the following value. ```json [ "birthdate", "nationalities" ] ``` It is expected that the authorization server implementation prepares values of the listed claims and passes them as the value of the `claimsForTx` request parameter when it calls the `/api/auth/userinfo/issue` API. The following is an example of the value of the `claimsForTx` request parameter. ```json { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] } ``` requestedVerifiedClaimsForTx: type: array items: type: array items: type: string description: | Names of verified claims that will be referenced when transformed claims are computed. transformedClaims: type: string description: | the value of the `transformed_claims` property in the `claims` request parameter of an authorization request or in the `claims` property in a request object. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. dpopNonce: type: string description: | The expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. userinfo_issue_request: type: object required: - token properties: token: type: string description: | The access token that has been passed to the userinfo endpoint by the client application. In other words, the access token which was contained in the userinfo request. claims: type: string description: | Claims in JSON format. As for the format, see [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). sub: type: string description: | The value of the `sub` claim. If the value of this request parameter is not empty, it is used as the value of the `sub` claim. Otherwise, the value of the subject associated with the access token is used. claimsForTx: type: string description: | Claim key-value pairs that are used to compute transformed claims. requestSignature: type: string description: | The Signature header value from the request. headers: type: array items: $ref: '#/components/schemas/pair' description: | HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature. verifiedClaimsForTx: type: array items: type: string description: | Values of verified claims requested indirectly by "transformed claims". x-mint: metadata: description: "Values of verified claims requested indirectly by \"transformed claims\"." content: | A client application may request "transformed claims". Each of transformed claims uses an existing claim as input. As a result, to compute the value of a transformed claim, the value of the referenced existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide values of existing claims for computation of transformed claims. A response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response parameter which is a list of verified claims that are referenced indirectly by transformed claims (cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` and pass them as the value of this `verifiedClaimsForTx` request parameter. The following is an example of the value of this request parameter. ``` [ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` property in the claims request parameter of an authorization request can be an array like below. ``` { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "userinfo": { "verified_claims": [ { "verification": { "trust_framework": { "value": "gold" } }, "claims": { "::18_or_above": null } }, { "verification": { "trust_framework": { "value": "silver" } }, "claims": { ":nationality_usa": null } } ] } } ``` For the example above, the value of this `verifiedClaimsForTx` property should be an array of size 2 and look like below. The first element is JSON including claims which have been verified under the trust framework `"gold"`, and the second element is JSON including claims which have been verified under the trust framework `"silver"`. ``` [ "{\"birthdate\":\"1970-01-23\"}", "{\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` userinfo_issue_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - JSON - JWT description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. signature: type: string description: | The signature header of the response message. signatureInput: type: string description: | The signature-input header of the response message contentDigest: type: string description: | The content-digest header of the response message idtoken_reissue_request: type: object required: - accessToken - refreshToken properties: accessToken: type: string description: | The value of this parameter should be (a) the value of the "`jwtAccessToken`" parameter in a response from the `/auth/token` API when the value is available, or (b) the value of the "`accessToken`" parameter in the response from the `/auth/token` API when the value of the "`jwtAccessToken`" parameter is not available. refreshToken: type: string description: | The value of this parameter should be the value of the "`refreshToken`" parameter in a response from the `/auth/token` API. sub: type: string description: | The value that should be used as the value of the "`sub`" claim of the ID token. This parameter is optional. When omitted, the value of the subject associated with the access token is used. claims: type: string description: | Additional claims that should be embedded in the payload part of the ID token. The format is a JSON object. This parameter is optional. idtHeaderParams: type: string description: | Additional parameters that should be embedded in the JWS header of the ID token. The format is a JSON object. This parameter is optional. idTokenAudType: type: string description: | The type of the "`aud`" claim of the ID token being issued. Valid values of this parameter are as follows. > | Value | Description | > | --- | --- | > | "`array`" | The type of the `aud` claim becomes an array of strings. | > | "`string`" | The type of the `aud` claim becomes a single string. | This parameter is optional, and the default value on omission is "`array`". This parameter takes precedence over the `idTokenAudType` property of {@link Service} (cf. {@link Service#getIdTokenAudType()}). idtoken_reissue_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: - OK - INTERNAL_SERVER_ERROR - CALLER_ERROR description: The next action that the implementation of the token endpoint should take. responseContent: type: string description: | The response content that can be used as the message body of the token response that should be returned from the token endpoint. idToken: type: string description: | The reissued ID token g_m_request: type: object required: - token properties: accessToken: type: string description: An access token to introspect. clientCertificate: type: string description: | Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method. dpop: type: string description: | `DPoP` header presented by the client during the request to the resource server. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htm: type: string description: | HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. htu: type: string description: | URL of the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: | The value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. 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 `/auth/gm` API with this `dpopNonceRequired` parameter `true` will force the Authlete API to check whether the DPoP proof JWT includes the expected `nonce` value. g_m_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: - OK - NO_CONTENT - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. 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. service_jwks_get_response: type: object properties: keys: type: array items: type: object additionalProperties: true description: | An object representing JWK. See [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) for more details. description: An array of [JWK](https://datatracker.ietf.org/doc/html/rfc7517)s. client_registration_request: type: object properties: json: type: string description: | Client metadata in JSON format that complies with [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) (OAuth 2.0 Dynamic Client Registration Protocol). token: type: string description: | The client registration access token. Used only for GET, UPDATE, and DELETE requests. clientId: type: string description: | The client's identifier. Used for GET, UPDATE, and DELETE requests client_registration_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: - BAD_REQUEST - CREATED - DELETED - INTERNAL_SERVER_ERROR - OK - UNAUTHORIZED - UPDATED description: | The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. client: $ref: '#/components/schemas/client' backchannel_authentication_request: type: object required: - parameters properties: parameters: type: string description: | Parameters of a backchannel authentication request which are the request parameters that the backchannel authentication endpoint of the OpenID provider implementation 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 backchannel authentication request from the client application. If the backchannel authentication endpoint of the OpenID provider implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client ID in Authorization header, the value should be extracted and set to this parameter. clientSecret: type: string description: | The client secret extracted from Authorization header of the backchannel authentication request from the client application. If the backchannel authentication endpoint of the OpenID provider implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in Authorization header, the value should be extracted and set to this parameter. clientCertificate: type: string description: | The client certification used in the TLS connection between the client application and the backchannel authentication endpoint of the OpenID provider. clientCertificatePath: type: array items: type: string description: | The client certificate path presented by the client during client authentication. Each element is a string in PEM format. 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/). cimdOptions: $ref: '#/components/schemas/cimd_options' description: | Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. backchannel_authentication_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - USER_IDENTIFICATION description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. clientId: type: integer format: int64 description: | The client ID of the client application that has made the backchannel authentication request. clientIdAlias: type: string description: | The client ID alias of the client application that has made the backchannel authentication request. clientIdAliasUsed: type: boolean description: | `true` if the value of the client_id request parameter included in the backchannel authentication request is the client ID alias. `false` if the value is the original numeric client ID. clientName: type: string description: | The name of the client application which has made the backchannel authentication request. scopes: type: array items: $ref: '#/components/schemas/scope' description: | The scopes requested by the backchannel authentication request. x-mint: metadata: description: "The scopes requested by the backchannel authentication request." content: | Basically, this property holds the value of the `scope` request parameter in the backchannel authentication request. However, because unregistered scopes are dropped on Authlete side, if the `scope` request parameter contains unknown scopes, the list returned by this property becomes different from the value of the `scope` request parameter. Note that `description` property and `descriptions` property of each `scope` object in the array contained in this property is always null even if descriptions of the scopes are registered. claimNames: type: array items: type: string description: | The names of the claims which were requested indirectly via some special scopes. See [5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) in OpenID Connect Core 1.0 for details. clientNotificationToken: type: string description: | The client notification token included in the backchannel authentication request. acrs: type: array items: type: string description: | The list of ACR values requested by the backchannel authentication request. Basically, this property holds the value of the `acr_values` request parameter in the backchannel authentication request. However, because unsupported ACR values are dropped on Authlete side, if the `acr_values` request parameter contains unrecognized ACR values, the list returned by this property becomes different from the value of the `acr_values` request parameter. hintType: type: string description: | The type of the hint for end-user identification which was included in the backchannel authentication request. hint: type: string description: | The value of the hint for end-user identification. sub: type: string description: | The value of the `sub` claim contained in the ID token hint included in the backchannel authentication request. bindingMessage: type: string description: | The binding message included in the backchannel authentication request. userCode: type: string description: | The binding message included in the backchannel authentication request. userCodeRequired: type: boolean description: | The flag which indicates whether a user code is required. `true` when both the `backchannel_user_code_parameter` metadata of the client (= Client's `bcUserCodeRequired` property) and the `backchannel_user_code_parameter_supported` metadata of the service (= Service's `backchannelUserCodeParameterSupported` property) are `true`. requestedExpiry: type: integer format: int32 description: | The requested expiry for the authentication request ID (`auth_req_id`). requestContext: type: string description: | The request context of the backchannel authentication request. It is the value of the request_context claim in the signed authentication request and its format is JSON. request_context is a new claim added by the FAPI-CIBA profile. warnings: type: array items: type: string description: | The warnings raised during processing the backchannel authentication request. ticket: type: string description: | The ticket which is necessary to call Authlete's `/auth/token/fail` API or `/auth/token/issue` API. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: | The dynamic scopes which the client application requested by the scope request parameter. deliveryMode: $ref: '#/components/schemas/delivery_mode' clientAuthMethod: type: string description: | The client authentication method that was performed. gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. grant: $ref: '#/components/schemas/grant' grantSubject: type: string description: | The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. backchannel_authentication_issue_request: type: object required: - ticket properties: ticket: type: string description: | The ticket issued from Authlete's `/backchannel/authentication` API. backchannel_authentication_issue_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: - INTERNAL_SERVER_ERROR - INVALID_TICKET - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. authReqId: type: string description: | The newly issued authentication request ID. expiresIn: type: integer format: int32 description: | The duration of the issued authentication request ID in seconds. interval: type: integer format: int32 description: | The minimum amount of time in seconds that the client must wait for between polling requests to the token endpoint. backchannel_authentication_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: | The ticket which should be deleted on a call of Authlete's `/backchannel/authentication/fail` API. This request parameter is not mandatory but optional. If this request parameter is given and the ticket belongs to the service, the specified ticket is deleted from the database. Giving this parameter is recommended to clean up the storage area for the service. reason: type: string enum: - ACCESS_DENIED - EXPIRED_LOGIN_HINT_TOKEN - INVALID_BINDING_MESSAGE - INVALID_TARGET - INVALID_USER_CODE - MISSING_USER_CODE - SERVER_ERROR - UNAUTHORIZED_CLIENT - UNKNOWN_USER_ID description: | The reason of the failure of the backchannel authentication request. This request parameter is not mandatory but optional. However, giving this parameter is recommended. If omitted, `SERVER_ERROR` is used as a reason. errorDescription: type: string description: | The description of the error. This corresponds to the `error_description` property in the response to the client. errorUri: type: string description: | The URI of a document which describes the error in detail. If this optional request parameter is given, its value is used as the value of the `error_uri` property. backchannel_authentication_fail_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - FORBIDDEN description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. backchannel_authentication_complete_request: type: object required: - ticket - result - subject properties: ticket: type: string description: | The ticket issued by Authlete's `/backchannel/authentication` API. result: type: string enum: - TRANSACTION_FAILED - ACCESS_DENIED - AUTHORIZED description: | The result of the end-user authentication and authorization. One of the following. Details are described in the description. subject: type: string description: | The subject (= unique identifier) of the end-user. sub: type: string description: | The value of the sub claim that should be used in the ID token. authTime: type: integer format: int64 description: | The time at which the end-user was authenticated. Its value is the number of seconds from `1970-01-01`. acr: type: string description: | The reference of the authentication context class which the end-user authentication satisfied. claims: type: string description: | Additional claims which will be embedded in the ID token. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. scopes: type: array items: type: string description: | Scopes to replace the scopes specified in the original backchannel authentication request with. When nothing is specified for this parameter, replacement is not performed. idtHeaderParams: type: string description: | JSON that represents additional JWS header parameters for ID tokens. errorDescription: type: string description: | The description of the error. If this optional request parameter is given, its value is used as the value of the `error_description` property, but it is used only when the result is not `AUTHORIZED`. To comply with the specification strictly, the description must not include characters outside the set `%x20-21 / %x23-5B / %x5D-7E`. errorUri: type: string description: | The URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. accessToken: type: string description: | The representation of an access token that may be issued as a result of the Authlete API call. accessTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. refreshTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. idTokenAudType: type: string description: | The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. backchannel_authentication_complete_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: - SERVER_ERROR - NO_ACTION - NOTIFICATION description: | The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. clientId: type: integer format: int64 description: | The client ID of the client application that has made the backchannel authentication request. clientIdAlias: type: string description: | The client ID alias of the client application that has made the backchannel authentication request. clientIdAliasUsed: type: boolean description: | `true` if the value of the client_id request parameter included in the backchannel authentication request is the client ID alias. `false` if the value is the original numeric client ID. clientName: type: string description: | The name of the client application which has made the backchannel authentication request. deliveryMode: $ref: '#/components/schemas/delivery_mode' clientNotificationEndpoint: type: string description: | The client notification endpoint to which a notification needs to be sent. This corresponds to the `client_notification_endpoint` metadata of the client application. clientNotificationToken: type: string description: | The client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification. This is the value of the `client_notification_token` request parameter included in the backchannel authentication request. authReqId: type: string description: | The newly issued authentication request ID. accessToken: type: string description: | The issued access token. refreshToken: type: string description: | The issued refresh token. idToken: type: string description: | The issued ID token. accessTokenDuration: type: integer format: int64 description: | The duration of the access token in seconds. refreshTokenDuration: type: integer format: int64 description: | The duration of the refresh token in seconds. idTokenDuration: type: integer format: int64 description: | The duration of the ID token in seconds. jwtAccessToken: type: string description: | The issued access token in JWT format. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. device_authorization_request: type: object required: - parameters properties: parameters: type: string description: | Parameters of a device authorization request which are the request parameters that the device authorization endpoint of the authorization server implementation 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 device authorization request from the client application. If the device authorization endpoint of the authorization server implementation supports Basic `Authentication` as a means of client authentication, and the request from the client application contained its client ID in `Authorization` header, the value should be extracted and set to this parameter. clientSecret: type: string description: | The client secret extracted from `Authorization` header of the device authorization request from the client application. If the device authorization endpoint of the authorization server implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in `Authorization` header, the value should be extracted and set to this parameter. clientCertificate: type: string description: | The client certificate used in the TLS connection between the client application and the device authorization endpoint of the authorization server. clientCertificatePath: type: array items: type: string description: | The client certificate path presented by the client during client authentication. Each element is a string in PEM format. 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/). cimdOptions: $ref: '#/components/schemas/cimd_options' description: | Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. device_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. clientId: type: integer format: int64 description: | The client ID of the client application that has made the device authorization request. clientIdAlias: type: string description: | The client ID alias of the client application that has made the device authorization request. clientIdAliasUsed: type: boolean description: | `true` if the value of the client_id request parameter included in the device authorization request is the client ID alias. `false` if the value is the original numeric client ID. clientName: type: string description: | The name of the client application which has made the device authorization request. clientAuthMethod: type: string description: | The client authentication method that should be performed at the device authorization endpoint. scopes: type: array items: $ref: '#/components/schemas/scope' description: | The scopes requested by the device authorization request. x-mint: metadata: description: "The scopes requested by the device authorization request." content: | Basically, this property holds the value of the scope request parameter in the device authorization request. However, because unregistered scopes are dropped on Authlete side, if the `scope` request parameter contains unknown scopes, the list returned by this property becomes different from the value of the `scope` request parameter. Note that `description` property and `descriptions` property of each scope object in the array contained in this property is always `null` even if descriptions of the scopes are registered. claimNames: type: array items: type: string description: | The names of the claims which were requested indirectly via some special scopes. See [5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) in OpenID Connect Core 1.0 for details. acrs: type: array items: type: string description: | The list of ACR values requested by the device authorization request. Basically, this property holds the value of the `acr_values` request parameter in the device authorization request. However, because unsupported ACR values are dropped on Authlete side, if the `acr_values` request parameter contains unrecognized ACR values, the list returned by this property becomes different from the value of the `acr_values` request parameter. deviceCode: type: string description: | The device verification code. This corresponds to the `device_code` property in the response to the client. userCode: type: string description: | The end-user verification code. This corresponds to the `user_code` property in the response to the client. verificationUri: type: string description: | The end-user verification URI. This corresponds to the `verification_uri` property in the response to the client. verificationUriComplete: type: string description: | The end-user verification URI that includes the end-user verification code. This corresponds to the `verification_uri_complete` property in the response to the client. expiresIn: type: integer format: int32 description: | The duration of the device verification code in seconds. This corresponds to the `expires_in` property in the response to the client. interval: type: integer format: int32 description: | The minimum amount of time in seconds that the client must wait for between polling requests to the token endpoint. This corresponds to the `interval` property in the response to the client. warnings: type: array items: type: string description: | The warnings raised during processing the backchannel authentication request. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: | The dynamic scopes which the client application requested by the scope request parameter. gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. grant: $ref: '#/components/schemas/grant' grantSubject: type: string description: | The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. device_verification_request: type: object required: - userCode properties: userCode: type: string description: | A user code. device_verification_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: - INTERNAL_SERVER_ERROR - NOT_EXIST - EXPIRED - VALID description: The next action that the authorization server implementation should take. clientId: type: integer format: int64 description: | The client ID of the client application to which the user code has been issued. clientIdAlias: type: string description: | The client ID alias of the client application to which the user code has been issued. clientIdAliasUsed: type: boolean description: | `true` if the value of the `client_id` request parameter included in the device authorization request is the client ID alias. `false` if the value is the original numeric client ID. clientName: type: string description: | The name of the client application to which the user code has been issued. scopes: type: array items: $ref: '#/components/schemas/scope' description: | The scopes requested by the device authorization request. Note that `description` property and `descriptions` property of each scope object in the array contained in this property is always null even if descriptions of the scopes are registered. claimNames: type: array items: type: string description: | The names of the claims which were requested indirectly via some special scopes. See [5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) in OpenID Connect Core 1.0 for details. This property is always `null` if the `scope` request parameter of the device authorization request does not include the `openid` scope even if special scopes (such as `profile`) are included in the request (unless the openid scope is included in the default set of scopes which is used when the `scope` request parameter is omitted). acrs: type: array items: type: string description: | The list of ACR values requested by the device authorization request. resources: type: array items: type: string description: | The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of this service that the client application belongs to. clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: | The attributes of the client. dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: | The dynamic scopes which the client application requested by the scope request parameter. expiresAt: type: integer format: int64 description: | Get the date in milliseconds since the Unix epoch (1970-01-01) at which the user code will expire. gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: | the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. grant: $ref: '#/components/schemas/grant' grantSubject: type: string description: | The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant. clientEntityId: type: string description: | The entity ID of the client. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. metadataDocumentLocation: type: string format: uri description: | The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. device_complete_request: type: object required: - userCode - result - subject properties: userCode: type: string description: | A user code. result: type: string enum: - TRANSACTION_FAILED - ACCESS_DENIED - AUTHORIZED description: | The result of the end-user authentication and authorization. One of the following. Details are described in the description. subject: type: string description: | The subject (= unique identifier) of the end-user. sub: type: string description: | The value of the sub claim that should be used in the ID token. authTime: type: integer format: int64 description: | The time at which the end-user was authenticated. Its value is the number of seconds from `1970-01-01`. acr: type: string description: | The reference of the authentication context class which the end-user authentication satisfied. claims: type: string description: | Additional claims which will be embedded in the ID token. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. scopes: type: array items: type: string description: | Scopes to replace the scopes specified in the original device authorization request with. When nothing is specified for this parameter, replacement is not performed. errorDescription: type: string description: | The description of the error. If this optional request parameter is given, its value is used as the value of the `error_description` property, but it is used only when the result is not `AUTHORIZED`. To comply with the specification strictly, the description must not include characters outside the set `%x20-21 / %x23-5B / %x5D-7E`. errorUri: type: string description: | The URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client. idtHeaderParams: type: string description: | JSON that represents additional JWS header parameters for ID tokens. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. accessTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. refreshTokenDuration: type: integer format: int64 description: | The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. idTokenAudType: type: string description: | The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. device_complete_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: - SERVER_ERROR - USER_CODE_NOT_EXIST - USER_CODE_EXPIRED - INVALID_REQUEST - SUCCESS description: | The next action that the authorization server implementation should take. token_get_list_response: type: object properties: start: type: integer format: int32 description: | Start index of search results (inclusive). end: type: integer format: int32 description: | End index of search results (exclusive). totalCount: type: integer format: int32 description: | Unique ID of a client developer. client: $ref: '#/components/schemas/client_limited' subject: type: string description: | Unique user ID of an end-user. accessTokens: type: array items: $ref: '#/components/schemas/access_token' description: | An array of access tokens. token_create_request: type: object required: - grantType properties: grantType: $ref: '#/components/schemas/grant_type' clientId: type: integer format: int64 description: | The ID of the client application which will be associated with a newly created access token. subject: type: string description: | The subject (= unique identifier) of the user who will be associated with a newly created access token. This parameter is required unless the grant type is `CLIENT_CREDENTIALS`. The value must consist of only ASCII characters and its length must not exceed 100. scopes: type: array items: type: string description: | The scopes which will be associated with a newly created access token. Scopes that are not supported by the service cannot be specified and requesting them will cause an error. accessTokenDuration: type: integer format: int64 description: | The duration of a newly created access token in seconds. If the value is 0, the duration is determined according to the settings of the service. refreshTokenDuration: type: integer format: int64 description: | The duration of a newly created refresh token in seconds. If the value is 0, the duration is determined according to the settings of the service. A refresh token is not created (1) if the service does not support `REFRESH_TOKEN`, or (2) if the specified grant type is either `IMPLICIT`or `CLIENT_CREDENTIALS`. properties: type: array items: $ref: '#/components/schemas/property' description: | Extra properties to associate with a newly created access token. Note that properties parameter is accepted only when the HTTP method of the request is POST and Content-Type of the request is `application/json`, so don't use `GET` method or `application/x-www-form-urlencoded` if you want to specify properties. clientIdAliasUsed: type: boolean description: | A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created. x-mint: metadata: description: "A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created." content: | This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). When you access the UserInfo endpoint (which is expected to be implemented using Authlete's `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`) `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo endpoint. Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create` API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`). accessToken: type: string description: | The value of the new access token. x-mint: metadata: description: "The value of the new access token." content: | The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not have to specify values of newly created access tokens. However, in some cases, for example, if you want to migrate existing access tokens from an old system to Authlete, you may want to specify values of access tokens. In such a case, you can specify the value of a newly created access token by passing a non-null value as the value of accessToken request parameter. The implementation of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of generating a new value when the request parameter holds a non-null value. Note that if the hash value of the specified access token already exists in Authlete's database, the access token cannot be inserted and the `/api/auth/token/create` API will report an error. refreshToken: type: string description: | The value of the new refresh token. x-mint: metadata: description: "The value of the new refresh token." content: | The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do not have to specify values of newly created refresh tokens. However, in some cases, for example, if you want to migrate existing refresh tokens from an old system to Authlete, you may want to specify values of refresh tokens. In such a case, you can specify the value of a newly created refresh token by passing a non-null value as the value of refreshToken request parameter. The implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter instead of generating a new value when the request parameter holds a non-null value. Note that if the hash value of the specified refresh token already exists in Authlete's database, the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error. accessTokenPersistent: type: boolean description: | Get whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is `true`, then the access token will not automatically expire and must be revoked or deleted manually at the service. If this request parameter is true, the `accessTokenDuration` request parameter is ignored. certificateThumbprint: type: string description: | The thumbprint of the MTLS certificate bound to this token. If this property is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client. The value of this property must be a SHA256 certificate thumbprint, base64url encoded. dpopKeyThumbprint: type: string description: | The thumbprint of the public key used for DPoP presentation of this token. If this property is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's `token_type` will be set to 'DPoP'. authorizationDetails: $ref: '#/components/schemas/authz_details' resources: type: array items: type: string format: uri description: | The value of the resources to associate with the token. This property represents the value of one or more `resource` request parameters which is defined in "RFC8707 Resource Indicators for OAuth 2.0". forExternalAttachment: type: boolean description: | the flag which indicates whether the access token is for an external attachment. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. acr: type: string description: | The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token. authTime: type: integer format: int64 description: | The time when the user authentication was performed during the course of issuing the access token. clientEntityIdUsed: type: boolean description: | Flag which indicates whether the entity ID of the client was used when the request for the access token was made. clientIdentifier: type: string description: | The client Identifier associated with the newly issued access token. sessionId: type: string description: | The session ID, which is the ID of the user's authentication session, associated with a newly created access token. metadataDocumentUsed: type: boolean description: | Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism rather than from the Authlete database. token_create_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - FORBIDDEN - OK description: The next action that the authorization server implementation should take. accessToken: type: string description: The newly issued access token. clientId: type: integer format: int64 description: | The ID of the client application associated with the access token. expiresAt: type: integer format: int64 description: | The time at which the access token expires. expiresIn: type: integer format: int64 description: | The duration of the newly issued access token in seconds. grantType: type: string description: | The grant type for the newly issued access token. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. refreshToken: type: string description: | The newly issued refresh token. scopes: type: array items: type: string description: | Scopes which are associated with the access token. subject: type: string description: | The subject (= unique identifier) of the user associated with the newly issued access token. tokenType: type: string description: | The token type of the access token. jwtAccessToken: type: string description: | If the authorization server is configured to issue JWT-based access tokens (= if `Service.accessTokenSignAlg` is set to a `non-null` value), a JWT-based access token is issued along with the original random-string one. authorizationDetails: $ref: '#/components/schemas/authz_details' forExternalAttachment: type: boolean description: | the flag which indicates whether the access token is for an external attachment. tokenId: type: string description: | Set the unique token identifier. refreshTokenScopes: type: array items: type: string description: | The scopes associated with the refresh token. May be null. clientIdentifier: type: string description: | The client Identifier that will be associated with a newly created access token. sessionId: type: string description: | The session ID associated with a newly created access token. NOTE: A refresh token must be associated with a session ID, which is the ID of the user's authentication session, in order to be used to obtain a [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html)-compliant ID token in the refresh token flow. token_update_request: type: object properties: accessToken: type: string description: | An access token. accessTokenExpiresAt: type: integer format: int64 description: | A new date at which the access token will expire in milliseconds since the Unix epoch (1970-01-01). If the `accessTokenExpiresAt` request parameter is not included in a request or its value is 0 (or negative), the expiration date of the access token is not changed. scopes: type: array items: type: string description: | A new set of scopes assigned to the access token. Scopes that are not supported by the service and those that the client application associated with the access token is not allowed to request are ignored on the server side. If the `scopes` request parameter is not included in a request or its value is `null`, the scopes of the access token are not changed. Note that `properties` parameter is accepted only when `Content-Type` of the request is `application/json`, so don't use `application/x-www-form-urlencoded` if you want to specify `properties`. properties: type: array items: $ref: '#/components/schemas/property' description: | A new set of properties assigned to the access token. If the `properties` request parameter is not included in a request or its value is null, the properties of the access token are not changed. accessTokenExpiresAtUpdatedOnScopeUpdate: type: boolean description: | A boolean request parameter which indicates whether the API attempts to update the expiration date of the access token when the scopes linked to the access token are changed by this request. accessTokenHash: type: string description: | The hash of the access token value. Used when the hash of the token is known (perhaps from lookup) but the value of the token itself is not. The value of the `accessToken` parameter takes precedence. accessTokenValueUpdated: type: boolean description: | A boolean request parameter which indicates whether to update the value of the access token in the data store. If this parameter is set to `true` then a new access token value is generated by the server and returned in the response. accessTokenPersistent: type: boolean description: | The flag which indicates whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is `true` then the access token will not automatically expire and must be revoked or deleted manually at the service. If this request parameter is `true`, the `accessTokenExpiresAt` request parameter is ignored. If this request parameter is `false`, the `accessTokenExpiresAt` request parameter is processed normally. certificateThumbprint: type: string description: | The thumbprint of the MTLS certificate bound to this token. If this property is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client. The value of this property must be a SHA256 certificate thumbprint, base64url encoded. dpopKeyThumbprint: type: string description: | The thumbprint of the public key used for DPoP presentation of this token. If this property is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's `token_type` will be set to 'DPoP'. authorizationDetails: $ref: '#/components/schemas/authz_details' forExternalAttachment: type: boolean description: | the flag which indicates whether the access token is for an external attachment. refreshTokenExpiresAt: type: integer format: int64 description: | A new date at which the access token will expire in milliseconds since the Unix epoch (1970-01-01). If the `refreshTokenExpiresAt` request parameter is not included in a request or its value is 0 (or negative), the expiration date of the refresh token is not changed. refreshTokenExpiresAtUpdatedOnScopeUpdate: type: boolean description: | A boolean request parameter which indicates whether the API attempts to update the expiration date of the refresh token when the scopes linked to the refresh token are changed by this request. tokenId: type: string description: | The token identifier. token_update_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: - INTERNAL_SERVER_ERROR - BAD_REQUEST - FORBIDDEN - NOT_FOUND - OK description: The next action that the authorization server implementation should take. accessToken: type: string description: The access token which has been specified by the request. accessTokenExpiresAt: type: integer format: int64 description: | The date at which the access token will expire. properties: type: array items: $ref: '#/components/schemas/property' description: | The extra properties associated with the access token. scopes: type: array items: type: string description: | The scopes associated with the access token. authorizationDetails: $ref: '#/components/schemas/authz_details' tokenType: type: string description: | The token type associated with the access token. forExternalAttachment: type: boolean description: | the flag which indicates whether the access token is for an external attachment. tokenId: type: string description: | Set the unique token identifier. refreshTokenExpiresAt: type: integer format: int64 description: | The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). token_revoke_request: type: object properties: accessTokenIdentifier: type: string description: | The identifier of an access token to revoke The hash of an access token is recognized as an identifier as well as the access token itself. refreshTokenIdentifier: type: string description: | The identifier of a refresh token to revoke. The hash of a refresh token is recognized as an identifier as well as the refresh token itself. clientIdentifier: type: string description: | The client ID of the access token to be revoked. Both the numeric client ID and the alias are recognized as an identifier of a client. subject: type: string description: | The subject of a resource owner. token_revoke_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. count: type: integer description: The number of tokens revoked jose_verify_request: type: object required: - jose properties: jose: type: string description: | A JOSE object. mandatoryClaims: type: array items: type: string description: | Mandatory claims that are required to be included in the JOSE object. clockSkew: type: integer format: int32 description: | Allowable clock skew in seconds. clientIdentifier: type: string description: | The identifier of the client application whose keys are required for verification of the JOSE object. signedByClient: type: boolean description: | The flag which indicates whether the signature of the JOSE object has been signed by a client application with the client's private key or a shared symmetric key. jose_verify_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. valid: type: boolean description: | The result of the verification on the JOSE object. signatureValid: type: boolean description: | The result of the signature verification. missingClaims: type: array items: type: string description: | The list of missing claims. invalidClaims: type: array items: type: string description: | The list of invalid claims. errorDescriptions: type: array items: type: string description: | The list of error messages. federation_configuration_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: - OK - NOT_FOUND - INTERNAL_SERVER_ERROR description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. federation_registration_request: type: object properties: entityConfiguration: type: string description: | The entity configuration of a relying party. trustChain: type: string description: | The trust chain of a relying party. federation_registration_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: - OK - BAD_REQUEST - NOT_FOUND - INTERNAL_SERVER_ERROR description: The next action that the authorization server implementation should take. responseContent: type: string description: | The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. client: $ref: '#/components/schemas/client' info_response: type: object required: - version - features properties: version: type: string description: The server version. features: type: array items: type: string description: the features that the server supports. configuration: type: object additionalProperties: type: string description: Server configuration properties as key-value pairs. serviceTokenCache: type: object description: Cache statistics for service tokens. properties: hitCount: type: integer format: int64 description: The number of cache hits. missCount: type: integer format: int64 description: The number of cache misses. loadSuccessCount: type: integer format: int64 description: The number of successful loads. loadFailureCount: type: integer format: int64 description: The number of failed loads. totalLoadTime: type: integer format: int64 description: The total load time in nanoseconds. evictionCount: type: integer format: int64 description: The number of evictions. evictionWeight: type: integer format: int64 description: The weight of evicted entries. client_extension_requestable_scopes_get_response: type: object properties: requestableScopes: type: array nullable: true items: type: string description: | The requestable scopes for this client. This is null if the Requestable Scopes per Client feature is not enabled for this client. client_extension_requestable_scopes_update_request: type: object properties: requestableScopes: type: array items: type: string description: | The set of scopes that the client application is allowed to request. This parameter will be one of the following. Details are described in the description. - an empty set - a set with at least one element If this parameter contains scopes that the service does not support, those scopes are just ignored. Also, if this parameter is `null` or is not included in the request, it is equivalent to calling `/client/extension/requestable_scopes/delete` API. client_extension_requestable_scopes_update_response: type: object properties: requestableScopes: type: array items: type: string hsk_create_request: type: object properties: kty: type: string description: | The key type (EC or RSA) use: type: string description: | The key on the HSM. When the key use is "sig" (signature), the private key on the HSM is used to sign data and the corresponding public key is used to verify the signature. When the key use is "enc" (encryption), the private key on the HSM is used to decrypt encrypted data which have been encrypted with the corresponding public key kid: type: string description: | Key ID for the key on the HSM. hsmName: type: string description: | The name of the HSM. The identifier for the HSM that sits behind the Authlete server. For example, "google". alg: type: string description: | The algorithm of the key on the HSM. When the key use is `"sig"`, the algorithm represents a signing algorithm such as `"ES256"`. When the key use is `"enc"`, the algorithm represents an encryption algorithm such as `"RSA-OAEP-256"`. It is rare that HSMs support all the algorithms listed in [RFC 7518 JSON Web Algorithms (JWA)](https://www.rfc-editor.org/rfc/rfc7518.html). When the specified algorithm is not supported by the HSM, the request to the `/hsk/create` API fails. hsk_create_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: - SUCCESS - INVALID_REQUEST - NOT_FOUND - SERVER_ERROR description: Result of the API call. hsk: $ref: '#/components/schemas/hsk' hsk_delete_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: - SUCCESS - INVALID_REQUEST - NOT_FOUND - SERVER_ERROR description: Result of the API call hsk: $ref: '#/components/schemas/hsk' hsk_get_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: - SUCCESS - INVALID_REQUEST - NOT_FOUND - SERVER_ERROR description: Result of the API call hsk: $ref: '#/components/schemas/hsk' hsk_get_list_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: - SUCCESS - INVALID_REQUEST - SERVER_ERROR description: Result of the API call hsks: type: array items: $ref: '#/components/schemas/hsk' description: List of HSK vci_metadata_request: type: object required: - pretty properties: pretty: type: boolean description: | The flag indicating whether the metadata is written in the pretty format or not. vci_metadata_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: - OK - NOT_FOUND - INTERNAL_SERVER_ERROR description: | The next action that the implementation of the credential issuer metadata endpoint (`/.well-known/openid-credential-issuer`) should take after getting a response from Authlete's `/vci/metadata` API. responseContent: type: string description: | Get the content that the implementation of the credential issuer metadata endpoint should use when it constructs a response. vci_jwtissuer_request: type: object required: - pretty properties: pretty: type: boolean description: | The flag indicating whether the metadata is written in the pretty format or not. vci_jwtissuer_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: - OK - NOT_FOUND - INTERNAL_SERVER_ERROR description: | The next action that the implementation of the JWT issuer metadata endpoint (`/.well-known/jwt-issuer`) should take after getting a response from Authlete's `/vci/jwtissuer` API. responseContent: type: string description: | Get the content that the implementation of the credential issuer metadata endpoint should use when it constructs a response. vci_jwks_request: type: object required: - pretty properties: pretty: type: boolean description: | The flag indicating whether the metadata is written in the pretty format or not. vci_jwks_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: - OK - NOT_FOUND - INTERNAL_SERVER_ERROR description: | The next action that the implementation of the JWK Set document endpoint of the credential issuer should take after getting a response from Authlete's `/vci/jwks` API. responseContent: type: string description: | Get the content that the implementation of the credential issuer metadata endpoint should use when it constructs a response. vci_offer_create_request: type: object properties: authorizationCodeGrantIncluded: type: boolean description: | The flag indicating whether the `authorization_code` object is included in the `grants` object. issuerStateIncluded: type: boolean description: | The flag indicating whether the `issuer_state` property is included in the `authorization_code` object in the `grants` object. preAuthorizedCodeGrantIncluded: type: boolean description: | The flag to include the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object in the `grants` object. subject: type: string description: The subject associated with the credential offer. duration: type: integer format: int64 description: The duration of the credential offer. context: type: string description: The general-purpose arbitrary string. properties: type: array items: $ref: '#/components/schemas/property' description: Extra properties to associate with the credential offer. jwtAtClaims: type: string description: | Additional claims that are added to the payload part of the JWT access token. authTime: type: integer format: int64 description: | The time at which the user authentication was performed during the course of issuing the credential offer. acr: type: string description: | The Authentication Context Class Reference of the user authentication performed during the course of issuing the credential offer. credentialConfigurationIds: type: array items: type: string description: | The value of the `credential_configuration_ids` array. x-mint: metadata: description: "The value of the `credential_configuration_ids` array." content: | ``` { "credential_issuer": "...", "credential_configuration_ids": [ ... ], "grants": { ... } } ``` This property is mandatory. txCode: type: string description: | The transaction code that should be associated with the credential offer. x-mint: metadata: description: "The transaction code that should be associated with the credential offer." content: | If this parameter is not empty and the `preAuthorizedCodeGrantIncluded` parameter is `true`, the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object will include the `tx_code` object. The length of the value of this parameter will be used as the value of the `length` property in the `tx_code` object. ``` { "credential_issuer": "...", "credential_configuration_ids": [ ... ], "grants": { "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", "tx_code": { "length": length } } } } ``` txCodeInputMode: type: string description: | The input mode of the transaction code. x-mint: metadata: description: "The input mode of the transaction code." content: | The value of this property will be used as the value of the `input_mode` property in the `tx_code` object. ``` { "credential_issuer": "...", "credential_configuration_ids": [ ... ], "grants": { "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", "tx_code": { "length": length, "input_mode": "..." } } } } ``` txCodeDescription: type: string description: | The description of the transaction code. x-mint: metadata: description: "The description of the transaction code." content: | The value of this property will be used as the value of the `description` property in the `tx_code` object. ``` { "credential_issuer": "...", "credential_configuration_ids": [ ... ], "grants": { "urn:ietf:params:oauth:grant-type:pre-authorized_code": { "pre-authorized_code": "...", "tx_code": { "length": length, "description": "..." } } } } ``` vci_offer_create_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 - FORBIDDEN - CALLER_ERROR - AUTHLETE_ERROR description: The result of the `/vci/offer/create` API call. info: $ref: '#/components/schemas/credential_offer_info' vci_offer_info_request: type: object properties: identifier: type: string description: The identifier of the credential offer. vci_offer_info_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: - OK - FORBIDDEN - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The result of the `/vci/offer/info` API call. info: $ref: '#/components/schemas/credential_offer_info' vci_single_parse_request: type: object properties: accessToken: type: string description: The access token that came along with the credential request. requestContent: type: string description: The message body of the credential request. vci_single_parse_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: - OK - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - INTERNAL_SERVER_ERROR description: The next action that the credential endpoint should take. responseContent: type: string description: The content of the response to the request sender. info: $ref: '#/components/schemas/credential_request_info' vci_single_issue_request: type: object properties: accessToken: type: string description: The access token that came along with the credential request. order: $ref: '#/components/schemas/credential_issuance_order' vci_single_issue_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: - OK - ACCEPTED - UNAUTHORIZED - FORBIDDEN - INTERNAL_SERVER_ERROR - CALLER_ERROR description: | The next action that the implementation of the credential endpoint should take. responseContent: type: string description: | The content of the response that the implementation of the credential endpoint should return. transactionId: type: string description: | The issued transaction ID. vci_batch_parse_request: type: object properties: accessToken: type: string description: The access token that came along with the credential request. requestContent: type: string description: The message body of the batch credential request. vci_batch_parse_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: - OK - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - INTERNAL_SERVER_ERROR description: The next action that the batch credential endpoint should take. responseContent: type: string description: The content of the response to the request sender. info: type: array items: $ref: '#/components/schemas/credential_request_info' description: | Information about the credential requests in the batch credential request. vci_batch_issue_request: type: object properties: accessToken: type: string description: The access token that came along with the credential request. orders: type: array items: $ref: '#/components/schemas/credential_issuance_order' description: The instructions for issuance of credentials and/or transaction IDs. vci_batch_issue_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: - OK - UNAUTHORIZED - FORBIDDEN - INTERNAL_SERVER_ERROR - CALLER_ERROR description: | The next action that the implementation of the batch credential endpoint should take. responseContent: type: string description: | The content of the response that the implementation of the batch credential endpoint should return. vci_deferred_parse_request: type: object properties: accessToken: type: string description: The access token that came along with the deferred credential request. requestContent: type: string description: The message body of the deferred credential request. vci_deferred_parse_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: - OK - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - INTERNAL_SERVER_ERROR description: The next action that the deferred credential endpoint should take. responseContent: type: string description: The content of the response to the request sender. info: $ref: '#/components/schemas/credential_request_info' description: Information about the credential request bound to the transaction ID. vci_deferred_issue_request: type: object properties: order: $ref: '#/components/schemas/credential_issuance_order' vci_deferred_issue_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: - OK - FORBIDDEN - INTERNAL_SERVER_ERROR - CALLER_ERROR description: | The next action that the implementation of the deferred credential endpoint should take. responseContent: type: string description: | The content of the response that the implementation of the deferred credential endpoint should return. authorization_ticket_info_request: type: object required: - ticket properties: ticket: type: string description: The ticket that has been issued from the `/auth/authorization` API. authorization_ticket_info_response: type: object properties: info: $ref: '#/components/schemas/authorization_ticket_info' description: Information about the ticket. action: type: string enum: - OK - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The result of the `/auth/authorization/ticket/info` API call. 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. authorization_ticket_update_request: type: object required: - ticket - info properties: ticket: type: string description: The ticket. info: type: string description: The information about the ticket. authorization_ticket_update_response: type: object properties: info: $ref: '#/components/schemas/authorization_ticket_info' description: Information about the ticket. action: type: string enum: - OK - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The result of the /auth/authorization/ticket/info API call. 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. native_sso_request: type: object required: - accessToken - deviceSecret properties: accessToken: type: string description: | The value of this parameter should be: (a) the value of the `jwtAccessToken` parameter in a response from the `/auth/token` API when the value is available, or (b) the value of the `accessToken` parameter in the response from the `/auth/token` API when the `jwtAccessToken` parameter is not available. refreshToken: type: string description: | The value of this parameter should be the value of the `refreshToken` parameter in a response from the `/auth/token` API. sub: type: string description: | The value that should be used as the value of the `sub` claim of the ID token. This parameter is optional. When omitted, the value of the subject associated with the access token is used. claims: type: string description: | Additional claims that should be embedded in the payload part of the ID token. The format is a JSON object. This parameter is optional. idtHeaderParams: type: string description: | Additional parameters that should be embedded in the JWS header of the ID token. The format is a JSON object. This parameter is optional. idTokenAudType: type: string description: | The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows: x-mint: metadata: description: "The type of the `aud` claim of the ID token being issued. Valid values of this parameter are as follows:" content: | - `"array"` The type of the `aud` claim becomes an array of strings. - `"string"` The type of the `aud` claim becomes a single string. This parameter is optional, and the default value when omitted is `"array"`. This parameter takes precedence over the `idTokenAudType` property of `Service`. deviceSecret: type: string description: | The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter. x-mint: metadata: description: "The device secret. The value of this parameter should be the value of the `deviceSecret` parameter in the response from the `/auth/token` API, if the parameter is present. Otherwise, the authorization server should generate a new device secret and specify it as the value of this parameter." content: | The specified device secret is included as the value of the `device_secret` property in the token response prepared by the `/nativesso` API. Additionally, if the `deviceSecretHash` request parameter is omitted, the device secret is used to compute the value of the `ds_hash` claim. In this case, the `ds_hash` claim will be the base64url-encoded SHA-256 hash of the device secret. deviceSecretHash: type: string description: | The device secret hash. The specified device secret hash is included as the value of the `ds_hash` claim in the ID token generated by the `/nativesso` API. If the `deviceSecretHash` request parameter is omitted, the value of the `deviceSecret` request parameter is used to compute the hash. native_sso_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: - OK - INTERNAL_SERVER_ERROR - CALLER_ERROR description: | The next action that the implementation of the token endpoint should take. responseContent: type: string description: | The response content that can be used as the message body of the token response that should be returned from the token endpoint. idToken: type: string description: | The issued ID token. native_sso_logout_request: type: object required: - sessionId properties: sessionId: type: string description: | The session ID of a user's authentication session. native_sso_logout_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: - OK - SERVER_ERROR - CALLER_ERROR description: | The next action that the API caller should take. count: type: integer description: | The number of deleted access/refresh token records. links: service_get: operationId: service_get_api parameters: serviceId: $request.path.serviceId service_get_list: operationId: service_get_list_api service_create: operationId: service_create_api service_update: operationId: service_update_api parameters: serviceId: $request.path.serviceId service_delete: operationId: service_delete_api parameters: serviceId: $request.path.serviceId client_get: operationId: client_get_api parameters: serviceId: $request.path.serviceId clientId: $response.body#/client/clientId client_get_list: operationId: client_get_list_api parameters: serviceId: $request.path.serviceId client_create: operationId: client_create_api parameters: serviceId: $request.path.serviceId client_update: operationId: client_update_api parameters: serviceId: $request.path.serviceId clientId: $response.body#/client/clientId client_delete: operationId: client_delete_api parameters: serviceId: $request.path.serviceId clientId: $response.body#/client/clientId par_request: operationId: pushed_auth_req_api parameters: serviceId: $request.path.serviceId authz_process: operationId: auth_authorization_api parameters: serviceId: $request.path.serviceId authz_issue: operationId: auth_authorization_issue_api parameters: serviceId: $request.path.serviceId ticket: $response.body#/ticket authz_fail: operationId: auth_authorization_fail_api parameters: serviceId: $request.path.serviceId ticket: $response.body#/ticket token_exchange: operationId: auth_token_api parameters: serviceId: $request.path.serviceId token_issue_direct: operationId: auth_token_issue_api parameters: serviceId: $request.path.serviceId token_issue: operationId: auth_token_issue_api parameters: serviceId: $request.path.serviceId token_revoke: operationId: auth_revocation_api parameters: serviceId: $request.path.serviceId token_introspect: operationId: auth_introspection_api parameters: serviceId: $request.path.serviceId userinfo: operationId: auth_userinfo_api parameters: serviceId: $request.path.serviceId native_sso: operationId: native_sso_api parameters: serviceId: $request.path.serviceId native_sso_logout: operationId: native_sso_logout_api parameters: serviceId: $request.path.serviceId refresh_token: operationId: auth_token_update_api parameters: serviceId: $request.path.serviceId device_poll_token: operationId: device_complete_api parameters: serviceId: $request.path.serviceId device_verify: operationId: device_verification_api parameters: serviceId: $request.path.serviceId jwks_get: operationId: service_jwks_get_api parameters: serviceId: $request.path.serviceId discovery_config: operationId: service_configuration_api parameters: serviceId: $request.path.serviceId device_authorization: operationId: device_authorization_api parameters: serviceId: $request.path.serviceId device_verification: operationId: device_verification_api parameters: serviceId: $request.path.serviceId device_complete: operationId: device_complete_api parameters: serviceId: $request.path.serviceId vci_offer_create: operationId: vci_offer_create_api parameters: serviceId: $request.path.serviceId vci_vp_metadata: operationId: vci_jwtissuer_api parameters: serviceId: $request.path.serviceId ciba_authentication: operationId: backchannel_authentication_api parameters: serviceId: $request.path.serviceId ciba_complete: operationId: backchannel_authentication_complete_api parameters: serviceId: $request.path.serviceId ciba_fail: operationId: backchannel_authentication_fail_api parameters: serviceId: $request.path.serviceId ciba_issue: operationId: backchannel_authentication_issue_api parameters: serviceId: $request.path.serviceId responses: '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: 404 resultMessage: '' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.'