NAV Navbar
curl java c# php ruby python go deno
  • Basics
  • Data Types
  • Service Management
  • Client Management
  • Authorization Endpoint
  • Token Endpoint
  • Introspection Endpoint
  • Revocation Endpoint
  • Userinfo Endpoint
  • JWK Set Endpoint
  • Discovery Endpoint
  • CIBA
  • Device Flow
  • Token Operations
  • Jose Object
  • Result Codes
  • Basics

    Host

    The hosts which provide Authlete APIs are as follows.

    Server Type URL
    Shared Server https://api.authlete.com
    Dedicated Server Decided after consultation.

    Request

    The basic settings that are required for requests to Authlete APIs are as follows.

    Basic Authentication

    All Authlete Web APIs require Basic Authentication. APIs to manage services (/service/*) require the pair of API key & API secret of a service owner. Other APIs require that of a service. If Authorization header is missing, a response with HTTP status of "401 Unauthorized" is returned.

    TLS

    All Authlete Web APIs require TLS (Transport Layer Security). If TLS is not used, a response with HTTP status of "400 Bad Request" is returned.

    Response

    Some reseponses from Authlete have the following parameters.

    Name Type Description
    resultCode string The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.
    resultMessage string A short message which explains the result of the API call.

    These parameters will be useful especially when you try to identify the cause of error. See Result Codes for more details.

    Also, the table below shows major error responses.

    Response Description
    400 Bad Request All APIs may return a response with HTTP status of 400 Bad Request due to one of the reasons listed below.
    • TLS is not used.
    • The content of Authorization header is malformed.
    401 Unauthorized All APIs may return a response with HTTP status of "401 Unauthorized" due to the following reason.
    • Authorization header is missing.
    403 Forbidden All APIs may return a response with HTTP status of "403 Forbidden" due to one of the reasons listed below.
    • The pair of API key & API secret specified in Authorization header is invalid.
    • The service owner or the service is locked.

    Data Types

    This section describes the details of data types.

    Access Token

    A data structure having information about an access token. The table below lists top-level properties of a JSON object that represents an "Access Token".

    Name Type Description
    accessTokenHash string

    The hash of the access token.

    accessTokenExpiresAt number

    The timestamp at which the access token will expire.

    refreshTokenHash string

    The hash of the refresh token.

    refreshTokenExpiresAt number

    The timestamp at which the refresh token will expire.

    createdAt number

    The timestamp at which the access token was first created.

    lastRefreshedAt number

    The timestamp at which the access token was last refreshed using the refresh token.

    clientId number

    The ID of the client associated with the access token.

    subject string

    The subject (= unique user ID) associated with the access token.

    grantType string

    The grant type of the access token when the access token was created.

    scopes string array

    The scopes associated with the access token.

    properties Property array

    The properties associated with the access token.

    Application Type

    Constant values that correspond to the values of application_type property described in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    Possible values are WEB and NATIVE.

    OpenID Connect Dynamic Client Registration 1.0 imposes additional requirements on redirect URIs base on the application type. The following description about application_type is an excerpt from the specification.

    OPTIONAL. Kind of the application. The default, if omitted, is web. The defined values are native or web. Web Clients using the OAuth Implicit Grant Type MUST only register URLs using the https scheme as redirect_uris; they MUST NOT use localhost as the hostname. Native Clients MUST only register redirect_uris using custom URI schemes or URLs using the http: scheme with localhost as the hostname. Authorization Servers MAY place additional constraints on Native Clients. Authorization Servers MAY reject Redirection URI values using the http scheme, other than the localhost case for Native Clients. The Authorization Server MUST verify that all the registered redirect_uris conform to these constraints. This prevents sharing a Client ID across different types of Clients.

    The description above says "The default, if omitted, is web." However, Authlete allows the applicationType property of Client to be null. It is because Authlete does not think it is appropriate to force all OAuth 2.0 clients to comply with the new requirements.

    Authorization Details

    A data structure that represents authorization_details defined by "OAuth 2.0 Rich Authorization Requests".

    A JSON object representing "Authorization Details" has elements property as a top-level property and its value is an array of objects. The listed below is common fileds that each object in the array must/can contain.

    Name Type Description
    type string

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

    locations string array

    The resources and/or resource servers

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

    actions string array

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

    dataTypes string array

    The data types.

    From "OAuth 2.0 Rich Authorization Requests": "An array of strings representing the kinds of data being requested from the resource."

    identifier string

    The identifier of a specific resource.

    From "OAuth 2.0 Rich Authorization Requests": "A string identifier indicating a specific resource available at the API."

    Note: each object in elements property may contain its own fields other than above.

    The following show an example of a JSON representing Authorization Details.

    {
      "type"      : "my_type",
      "locations" : [ "loc0", "loc1" ],
      "actions"   : [ "act0", "act1" ],
      "identifier": "my_id",
      "prop0"     : "a",
      "prop1"     : [ "b", "c" ],
      "prop2"     : {
      "sub0"      : "d",
      "sub1"      : [ "e", "f" ]
    }

    Claim Type

    Constant values that correspond to the claim types described in OpenID Connect Core 1.0, 5.6. Claim Types.

    Possible values are NORMAL, AGGREGATED and DISTRIBUTED.

    Client Authentication Method

    Constant values that represents client authentication methods at an authorizaion server.

    Possible values are as follows.

    Value Description
    NONE

    This value corresponds to none described in OpenID Connect Core 1.0, 9. Client Authentication.

    CLIENT_SECRET_BASIC

    This value corresponds to client_secret_basic described in OpenID Connect Core 1.0, 9. Client Authentication. This is the Basic Authentication based method described in RFC 6749, 2.3. Client Authentication, which authorization servers must support.

    CLIENT_SECRET_POST

    This value corresponds to client_secret_post described in OpenID Connect Core 1.0, 9. Client Authentication. This is the method using the request body, which is described in RFC 6749, 2.3. Client Authentication.

    CLIENT_SECRET_JWT

    This value corresponds to client_secret_jwt described in OpenID Connect Core 1.0, 9. Client Authentication.

    This is available since Authlete 2.0.

    PRIVATE_KEY_JWT

    This value corresponds to private_key_jwt described in OpenID Connect Core 1.0, 9. Client Authentication.

    This is available since Authlete 2.0.

    TLS_CLIENT_AUTH

    This value indicates that clients authenticate with the Authorization Server using X.509 certificates as defined in "Mutual TLS Profiles for OAuth Clients".

    This is available since Authlete 2.0.

    SELF_SIGNED_TLS_CLIENT_AUTH

    This value indicates that clients authenticate with the Authorization Server using self-signed certificates as defined in "Mutual TLS Profiles for OAuth Clients".

    This is available since Authlete 2.0.

    Client Extension

    There are some attributes that belong to a client application but should not be changed by the developer of the client application. Basically, this object holds such attributes.

    For example, an authorization server may narrow the range of scopes (permissions) that a particular client application can request. In this case, it is meaningless if the developer of the client application can freely decide the set of requestable scopes. It is not the developer of the client application but the administrator of the authorization server that should be allowed to define the set of scopes that the client application can request. This data structure has properties listed in the following table.

    Name Type Description
    requestableScopes string array

    The set of scopes that the client application is allowed to request. This paramter will be one of the following.

    • 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 boolean

    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 number

    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.

    This property is available since Authlete 2.1.

    refreshTokenDuration number

    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.

    This property is available since Authlete 2.1.

    Client Type

    Constant values that correspond to the client types described in RFC 6749, 2.1. Client Types.

    Possible values are CONFIDENTIAL and PUBLIC.

    Client

    A data structure that represents a client application. The table below lists top-level properties of the JSON object which represents a "Client".

    Name Type Description
    number number

    The sequential number of the client application. The value of this property is assigned by Authlete.

    serviceNumber number

    The sequential number of the service of the client application. The value of this property is assigned by Authlete.

    developer string

    The developer of the client application.

    clientName string

    The name of the client application.

    This property corresponds to client_name in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    clientNames Tagged Value array

    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 string

    The description about the client application.

    descriptions Tagged Value array

    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 number

    The client ID. The value of this property is assigned by Authlete.

    clientSecret string

    The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete.

    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 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 string

    The alias of the client ID.

    Note that the client ID alias is recognized only when this client's clientIdAliasEnabled property is set to true AND the service's clientIdAliasEnabled property is also set to true.

    clientIdAliasEnabled boolean

    The flag to indicate whether the client ID alias is enabled or not.

    Note that Service object also has clientIdAliasEnabled property. If the service's clientIdAliasEnabled property is set to false, the client ID alias of this client is not recognized even if this client's clientIdAliasEnabled property is set to true.

    clientType string

    The client type, either CONFIDENTIAL or PUBLIC. See RFC 6749, 2.1. Client Types for details.

    applicationType string

    The application type. WEB, NATIVE or null. The value of this property affects the validation steps for a redirect URI. See the description about redirectUris property for more details.

    This property corresponds to application_type in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    logoUri string

    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.

    logoUris Tagged Value array

    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 string array

    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.

    tlsClientCertificateBoundAccessTokens boolean

    The flag to indicate whether this client use TLS client certificate bound access tokens.

    This property is available since Authlete 2.0.

    dynamicallyRegistered boolean

    The flag to indicate whether this client has been registered dynamically. For more details, see RFC 7591 (OAuth 2.0 Dynamic Client Registration Protocol).

    This property is available since Authlete 2.1.

    softwareId string

    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 of RFC 7591 (OAuth 2.0 Dynamic Client Registration Protocol).

    This property is available since Authlete 2.1.

    softwareVersion string

    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 of RFC 7591 (OAuth 2.0 Dynamic Client Registration Protocol).

    This property is available since Authlete 2.1.

    registrationAccessTokenHash string

    The hash of the registration access token for this client.

    This property is available since Authlete 2.1.

    createdAt number

    The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

    modifiedAt number

    The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

    grantTypes string array

    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.

    responseTypes string array

    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.

    redirectUris string array

    Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows.

    Requirements by RFC 6749
    (From RFC 6749, 3.1.2. Redirection Endpoint)
    • 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, application_type")
    • The scheme of the redirect URI used for Implicit Grant by a client application whose application type 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 for details), but OpenID Connect requires exact match.

    authorizationDataTypes string

    The data types that this client may use as values of the type field in authorization_details.

    This property corresponds to the authorization_data_types metadata. See "OAuth 2.0 Rich Authorization Requests" (RAR) for details.

    This property is available since Authlete 2.2.

    authorizationSignAlg string

    The JWS alg algorithm for signing authorization responses. One of the values listed in JWS Algorithm.

    This property corresponds to authorization_signed_response_alg in 5. Client Metadata of Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM).

    This property is available since Authlete 2.1.

    authorizationEncryptionAlg string

    The JWE alg algorithm for encrypting authorization responses. One of the values listed in JWE Algorithm.

    This property corresponds to authorization_encrypted_response_alg in 5. Client Metadata of Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM).

    This property is available since Authlete 2.1.

    authorizationEncryptionEnc string

    The JWE enc algorithm for encrypting authorization responses.

    This property corresponds to authorization_encrypted_response_enc in 5. Client Metadata of Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM).

    This property is available since Authlete 2.1.

    tokenAuthMethod string

    The client authentication method that the client application declares that it uses at the token endpoint. One of the values listed in Client Authentication Method.

    This property corresponds to token_endpoint_auth_method in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    tokenAuthSignAlg string

    The value of alg header parameter of JWS which is used for client authentication at the token endpoint. One of the values listed in JWS Algorithm except NONE.

    Note that this property is used only for the two JWT-based client authentication, namely, PRIVATE_KEY_JWT and CLIENT_SECRET_JWT (see Cient Authentication Method).

    This property corresponds to token_endpoint_auth_signing_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    selfSignedCertificateKeyId string

    The key ID of a JWK containing a self-signed certificate of this client.

    This property is available since Authlete 2.0.

    tlsClientAuthSubjectDn string

    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.

    This property is available since Authlete 2.0.

    tlsClientAuthSanDns string

    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.

    This property is available since Authlete 2.1.

    tlsClientAuthSanUri string

    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.

    This property is available since Authlete 2.1.

    tlsClientAuthSanIp string

    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.

    This property is available since Authlete 2.1.

    tlsClientAuthSanEmail string

    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.

    This property is available since Authlete 2.1.

    parRequired string

    The flag to inducate 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".

    This property is available since Authlete 2.2.

    requestObjectRequired string

    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)".

    This property is available since Authlete 2.2.

    requestSignAlg string

    The value of alg header parameter of JWS that the client application uses for signing a request object. One of the values listed in JWS Algorithm.

    If the value of this property is not null, request objects sent from the client application must be signed using the algorithm. Request objects signed by other algorithms are rejected. Note that null and NONE are different for this property.

    If the value of this property indicates an asymmetric signing algorithm, the client application must make available its JWK Set which contains a public key for the service to verify the signature of the request object at the URL referred to by its jwksUri configuration property.

    This property corresponds to request_object_signing_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    This property is available since Authlete 2.0.

    requestEncryptionAlg string

    The value of alg header parameter of JWE that the client application uses for encrypting a request object. One of the supported values listed in JWE Algorithm.

    Regardless of whether the value of this property is null or not, the client application may and may not encrypt a request object. Furthermore, the client application may use other supported encryption algorithms.

    This property corresponds to request_object_encryption_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    requestEncryptionEnc string

    The value of enc header parameter of JWE that the client application uses for encrypting a request object. One of the values listed in JWE Encryption Algorithm.

    This property corresponds to request_object_encryption_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    requestUris string array

    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 requestUris property is used for the pre-registration. See OpenID Connect Core 1.0, 6.2. Passing a Request Object by Reference for details.

    defaultMaxAge number

    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.

    defaultAcrs string array

    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 string

    The value of alg header parameter of JWS that the client application requires the service to use for signing an ID token. One of the values listed in JWS Algorithm.

    NONE may be specified, but in that case, the client application cannot obtain an ID token from the service. That is, an authorization request requesting an ID token fails.

    This property corresponds to id_token_signed_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    idTokenEncryptionAlg string

    The value of alg header parameter of JWE that the client application requires the service to use for encrypting an ID token. One of the supported values listed in JWE Algorithm.

    If the value of this property indicates an asymmetric encryption algorithm, the client application must make available its JWK Set which contains a public key for encryption at the URL referred to by its jwksUri configuration property.

    This property corresponds to id_token_encrypted_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    idTokenEncryptionEnc string

    The value of enc header parameter of JWE that the client application requires the service to use for encrypting an ID token. One of the values listed in JWE Encryption Algorithm.

    This property corresponds to id_token_encrypted_response_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    authTimeRequired boolean

    The flag to indicate whether this client requires auth_time claim to be embedded in the ID token.

    This property is set to true if the client application requires the auth_time claim to be in an ID token. Regardless of the value of this property, Authlete embeds the auth_time claim when authTime parameter in the /auth/authorization/issue request is not 0 and does not do it when authTime is 0.

    This property corresponds to require_auth_time in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    subjectType string

    The subject type that the client application requests. Either PUBLIC or PAIRWISE. Details about the subject type are described in OpenID Connect Core 1.0, 8. Subjct Identifier Types.

    Note that PAIRWISE is only available since Authlete 2.2.

    This property corresponds to subject_type in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    sectorIdentifier string

    The sector identifier which is a URL starting with https. This URL is used by the service to calculate pairwise subject values. See OpenID Connect Core 1.0, 8.1. Pairwise Identifier Algorithm.

    This property corresponds to sector_identifier_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    This property is depricated since Authlete 2.1.

    sectorIdentifierUri string

    The value of the sector identifier URI.

    This represents the sector_identifier_uri client metadata which is defined in 2. Client Metadata of OpenID Connect Dynamic Client Registration 1.0.

    This property is available since Authlete 2.1.

    derivedSectorIdentifier string

    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.

    This property is available since Authlete 2.2.

    jwksUri string

    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. JSON Web Key Set (JWK Set) Format". The JWK Set must not include private keys of the client application.

    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 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.

    jwks string

    The content of the JWK Set of the client application. The format is described in "JSON Web Key (JWK), 5. JSON Web Key Set (JWK Set) Format". Of course, the JWK Set must not include private keys of the client application.

    OpenID Connect Dynamic Client Registration 1.0 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 in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    userInfoSignAlg string

    The value of alg header parameter of JWS that the client application requires the service to use for signing the JWT returned from the user info endpoint. One of the values listed in JWS Algorithm.

    If both userInfoSignAlg and userInfoEncryptionAlg are null, the format of the response from the user info endpoint is a plain JSON (not JWT). Note that null and NONE are different for this property.

    This property corresponds to userinfo_signed_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    userInfoEncryptionAlg string

    The value of alg header parameter of JWE that the client application requires the service to use for encrypting the JWT returned from the user info endpoint. One of the supported values listed in JWE Algorithm.

    If the value of this property indicates an asymmetric encryption algorithm, the client application must make available its JWK Set which contains a public key for encryption at the URL referred to by its jwksUri configuration property.

    If both userInfoSignAlg and userInfoEncryptionAlg are null, the format of the response from the user info endpoint is a plain JSON (not JWT).

    This property corresponds to userinfo_encrypted_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    userInfoEncryptionEnc string

    The value of enc header parameter of JWE that the client application requires the service to use for encrypting the JWT returned from the user info endpoint. One of the values listed in JWE Encryption Algorithm.

    This property corresponds to userinfo_encrypted_response_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    loginUri string

    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.

    tosUri string

    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.

    tosUris Tagged Value array

    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 string

    The URL pointing to the page which describes the policy as to how end-users' profile data are used.

    This property corresponds to policy_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

    policyUris Tagged Value array

    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 string

    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.

    clientUris Tagged Value array

    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 string

    The backchannel token delivery mode.

    This property corresponds to the backchannel_token_delivery_mode metadata. One of the values listed in Delivery Mode. The backchannel token delivery mode is defined in the specification of "CIBA (Client Initiated Backchannel Authentication)".

    This property is depricated since Authlete 2.1.

    bcNotificationEndpoint string

    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)".

    This property is depricated since Authlete 2.1.

    bcRequestSignAlg string

    The signature algorithm of the request to the backchannel authentication endpoint. One of the asymmetric algorithm values listed in JWS Algorithm.

    This property corresponds to the backchannel_authentication_request_signing_alg metadata. The backchannel token delivery mode is defined in the specification of "CIBA (Client Initiated Backchannel Authentication)".

    This property is depricated since Authlete 2.1.

    bcUserCodeRequired boolean

    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.

    This property is depricated since Authlete 2.1.

    attributes Pair array

    The attributes of this client.

    This property is available since Authlete 2.2.

    extension ClientExtension

    The extended information about this client. See Client Extension for more details.

    Display

    Constant values that correspond to the display values described in OpenID Connect Core 1.0, 3.1.2.1. Authentication Request.

    Possible values are PAGE, POPUP, TOUCH and WAP.

    Prompt

    Constant values that correspond to the prompt values described in OpenID Connect Core 1.0, 3.1.2.1. Authentication Request.

    Possible values are NONE, LOGIN, CONSENT and SELECT_ACCOUNT.

    Grant Type

    Constant values that correspond to the values of grant_type request parameter for token endpoint.

    Possible values are as follows.

    Value Description
    AUTHORIZATION_CODE

    This corresponds to authorization_code defined in RFC 6749, 4.1.3. Access Token Request for Authorization Code Grant.

    IMPLICIT

    This corresponds to implicit defined in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata for Implicit Grant.

    PASSWORD

    This corresponds to password defined in RFC 6749, 4.3.2. Access Token Request for Resource Owner Password Credentials Grant.

    CLIENT_CREDENTIALS

    This corresponds to client_credentials defined in RFC 6749, 4.4.2. Access Token Request for Client Credentials Grant.

    REFRESH_TOKEN

    This corresponds to refresh_token defined in RFC 6749, 6. Refreshing an Access Token.

    CIBA

    This corresponds to urn:openid:params:grant-type:ciba defined in the specification of CIBA (Client Initiated Backchannel Authentication).

    This property is available since Authlete 2.1.

    DEVICE_CODE

    This corresponds to urn:ietf:params:oauth:grant-type:device_code defined in the specification of Device Flow.

    This property is available since Authlete 2.1.

    Note that implicit cannot be used as a value for grant_type request parameter.

    JWS Algorithm

    Constant values that correspond to the values of alg header parameter of JSON Web Signature (JWS). For more details, see JSON Web Algorithms (JWA), 3.1. "alg" (Algorithm) Header Parameter Values for JWS.

    Possible values are as follows.

    • NONE
    • HS256
    • HS384
    • HS512
    • RS256
    • RS384
    • RS512
    • ES256
    • ES384
    • ES512
    • PS256
    • PS384
    • PS512
    • ES256K
    • EdDSA

    JWE Algorithm

    Constant values that correspond to the values of alg header parameter of JSON Web Encryption (JWE), which are described in JSON Web Algorithms (JWA), 4.1. "alg" (Algorithm) Header Parameter Values for JWE.

    Possible values are as follows.

    • 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 Encryption Algorithm

    Constant values that correspond to the values of enc header parameter of JSON Web Encryption (JWE). For more details, see JSON Web Algorithms (JWA), 5.1. "enc" (Encryption Algorithm)Header Parameter Values for JWE.

    Possible values are as follows.

    • A128CBC_HS256
    • A192CBC_HS384
    • A256CBC_HS512
    • A128GCM
    • A192GCM
    • A256GCM

    Pair

    A simple key-value data structure for general purpose.

    Name Type Description
    key string

    The key part.

    value string

    The value part.

    Property

    A data structure that consists of a string key, a string value, and a boolean flag that shows whether this data is visible to client applications or not.

    This data type is used mainly to represent an extra property that is associated with an access token. Some Authlete APIs (such as /api/auth/token API) accept an array of properties via properties request parameter and associate the properties with an access token.

    Name Type Description
    key string

    The key part.

    value string

    The value part.

    hidden boolean

    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

    Constant values that correspond to response_type request parameter for authorization endpoint. RFC 6749 defines two values, code and token. The other values are added by OAuth 2.0 Multiple Response Type Encding Practices, which is a part of Open ID Connect specification.

    Possible values are as follows.

    Value Description
    NONE

    This corresponds to "none" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 4. None Response Type.

    CODE

    This corresponds to "code" defined in RFC 6749, 4.1.1. Authorization Request for Authorization Code Grant.

    TOKEN

    This corresponds to "token" defined in RFC 6749, 4.2.1. Authorization Request for Implicit Grant.

    ID_TOKEN

    This corresponds to "id_token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 3. ID Token Response Type.

    CODE_TOKEN

    This corresponds to "code token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

    CODE_ID_TOKEN

    This corresponds to "code id_token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

    ID_TOKEN_TOKEN

    This corresponds to "id_token token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

    CODE_ID_TOKEN_TOKEN

    This corresponds to "code id_token token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

    Scope

    A data structure for a scope which is described in RFC 6749, Access Token Scope. The data structure has properties listed in the following table.

    Name Type Description
    name string

    The name of the scope.

    defaultEntry boolean

    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 string

    The description of the scope.

    attributes Pair array

    The attributes of the scope.

    This property is available since Authlete 2.1.

    Service

    A data structure that represent a service (= an authorization server). The table below lists top-level properties of a JSON object which represents a service.

    Name Type Description
    number number

    The sequential number of the service. The value of this property is assigned by Authlete.

    serviceOwnerNumber number

    The sequential number of the service owner of the service. The value of this property is assigned by Authlete.

    serviceName string

    The name of the service.

    issuer string

    The issuer identifier of the service. A URL that starts with https:// and has no query or fragment component. For example, https://example.com.

    The value of this property is used as iss claim in an ID token and issuer property in the OpenID Provider Metadata.

    description string

    The description about the service.

    apiKey number

    The API key. The value of this property is assigned by Authlete.

    apiSecret string

    The API secret. A random 256-bit value encoded by base64url (43 letters). The value of this property is assigned by Authlete.

    clientsPerDeveloper number

    The maximum number of client applications that a developer is allowed to create. 0 means no limit.

    clientIdAliasEnabled string

    The flag to indicate whether the 'Client ID Alias' feature is enabled or not.

    When a new client is created, Authlete generates a numeric value and assigns it as a client ID to the newly created client. In addition to the client ID, each client can have a client ID alias. The client ID alias is, however, recognized only when this property (clientIdAliasEnabled) is true.

    metadata Pair array

    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 number

    The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

    modifiedAt number

    The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

    authenticationCallbackEndpoint string

    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 string

    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 string

    API secret for Basic authentication at the authentication callback endpoint.

    supportedSnses string

    SNSes you want to support 'social login' in the UI at the authorization endpoint provided by Authlete. You need to register a client application in each SNS that is set as this parameter and set Authlete server's /api/sns/redirection as the redirection endpoint of the client application.

    snsCredentials string

    SNS credentials which Authlete uses to make requests to SNSes. The format is JSON.

    supportedAcrs string array

    Values of 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.

    developerAuthenticationCallbackEndpoint string

    A Web API endpoint for developer authentication which is to be prepared on the server side.

    The endpoint must be implemented if you use Developer Console. The developer authentication at the login page of Developer Console is performed by making a POST request to this endpoint.

    developerAuthenticationCallbackApiKey string

    API key for Basic authentication at the developer authentication callback endpoint.

    If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the developer authentication callback endpoint.

    developerAuthenticationCallbackApiSecret string

    API secret for Basic authentication at the developer authentication callback endpoint.

    supportedDeveloperSnses string

    SNSes you want to support 'social login' in the login page of Developer Console provided by Authlete. You need to register a client application in each SNS checked here and set Authlete server's /api/developer/sns/redirection as the redirection endpoint of the client application.

    developerSnsCredentials string

    SNS credentials which Authlete uses to make requests to SNSes. The format is JSON.

    supportedGrantTypes string array

    Values of grant_type request parameter that the service supports. Valid values are listed in Grant Type.

    The value of this property is used as grant_types_supported property in the OpenID Provider Metadata.

    supportedResponseTypes string array

    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.

    supportedAuthorizationDataTypes string array

    The supported data types that can be used as values of the type field in authorization_details.

    This property corresponds to the authorization_data_types_supported metadata. See "OAuth 2.0 Rich Authorization Requests" (RAR) for details.

    This property is available since Authlete 2.2.

    supportedServiceProfiles string array

    The profiles that this service supports. One of the values listed in Service Profile.

    This property is available since Authlete 2.0.

    errorDescriptionOmitted boolean

    The flag to indicate whether the error_description response parameter is omitted.

    According to RFC 6749, 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 boolean

    The flag to indicate whether the error_uri response parameter is omitted.

    According to RFC 6749, 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 string

    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.

    directAuthorizationEndpointEnabled boolean

    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 string array

    UI locales that the service supports.

    Each element is a language tag defined in RFC 5646. For example, en-US and ja-JP.

    The value of this property is used as ui_locales_supported property in the OpenID Provider Metadata.

    supportedDisplays string array

    Values of display request parameter that service supports. Valid values are listed in Display.

    The value of this property is used as display_values_supported property in the OpenID Provider Metadata.

    pkceRequired boolean

    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 (Proof Key for Code Exchange by OAuth Public Clients) for details about code_challenge request parameter.

    pkceS256Required boolean

    The flag to indicate whether S256 is always required as the code challenge method whenever PKCE (RFC 7636) 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.

    This property is available since Authlete 2.1.

    authorizationResponseDuration number

    The duration of authorization response JWTs.

    Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) 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.

    This property is available since Authlete 2.1.

    tokenEndpoint string

    The token endpoint 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.

    directTokenEndpointEnabled boolean

    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 string array

    Client authentication methods supported by the token endpoint of the service. Valid values are listed in Client Authentication Method. Note that CLIENT_SECRET_JWT and PRIVATE_KEY_JWT are only supported since Authlete 2.0.

    The value of this property is used as token_endpoint_auth_methods_supports property in the OpenID Provider Metadata.

    missingClientIdAllowed boolean

    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.

    This property is available since Authlete 2.1.

    revocationEndpoint string

    The revocation endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/revocation.

    directRevocationEndpointEnabled boolean

    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 string array

    Client authentication methods supported at the revocation endpoint.

    This property is available since Authlete 2.0.

    introspectionEndpoint string

    The URI of the introspection endpoint.

    directIntrospectionEndpointEnabled boolean

    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 string arrray

    Client authentication methods supported at the introspection endpoint. One of the values listed in Client Authentication Method.

    This property is available since Authlete 2.0.

    pushedAuthReqEndpoint string

    The URI of the pushed authorization request endpoint.

    This property corresponds to the pushed_authorization_request_endpoint metadata defined in " 5. Authorization Server Metadata" of OAuth 2.0 Pushed Authorization Requests.

    This property is available since Authlete 2.2.

    pushedAuthReqDuration number

    The duration of pushed authorization requests.

    OAuth 2.0 Pushed Authorization Requests 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.

    This property is available since Authlete 2.2.

    parRequired boolean

    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.

    This property is available since Authlete 2.2.

    requestObjectRequired boolean

    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.

    This property is available since Authlete 2.2.

    traditionalRequestObjectProcessingApplied boolean

    The flag to indicate whether a request object is processed based on rules defined in OpenID Connect Core 1.0 or JAR (JWT Secured Authorization Request).

    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.

    This property is available since Authlete 2.2.

    mutualTlsValidatePkiCertChain boolean

    The flag to indicate whether this service validates certificate chains during PKI-based client mutual TLS authentication.

    This property is available since Authlete 2.0.

    trustedRootCertificates string array

    The list of root certificates trusted by this service for PKI-based client mutual TLS authentication.

    This property is available since Authlete 2.0.

    mtlsEndpointAliases NamedUri array

    The MTLS endpoint aliases.

    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.

    The aliases will be embedded in the response from the discovery endpoint like the following.

    {
         ......,
         "mtls_endpoint_aliases": {
             "token_endpoint":         "https://mtls.example.com/token",
             "revocation_endpoint":    "https://mtls.example.com/revo",
             "introspection_endpoint": "https://mtls.example.com/introspect"
         }
     }

    This property is available since Authlete 2.1.

    accessTokenType string

    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, the value of this property should be Bearer.

    See RFC 6749 (OAuth 2.0), 7.1. Access Token Types for details.

    tlsClientCertificateBoundAccessTokens boolean

    The flag to indicate whether this service supports issuing TLS client certificate bound access tokens.

    This property is available since Authlete 2.0.

    accessTokenDuration number

    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.

    singleAccessTokenPerSubject boolean

    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 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 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 string

    The signature algorithm of access tokens. One of the values listed in JWS Algorithm except for symmetric algorithms (HS256, HS384 and HS512). When null is set, access tokens issued by this service are just random strings. On the other hand, when a non-null value is set, access tokens issued by this service are JWTs and the value of this property is used as the signature algorithm of the JWTs.

    This property is available since Authlete 2.1. Access tokens generated by older Authlete versions are always random strings.

    accessTokenSignatureKeyId string

    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 (See RFC 7517 for details about JWK). 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.

    This property is available since Authlete 2.1.

    refreshTokenDuration number

    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 boolean

    The flag to indicate whether the remaining duration of the used refresh token is taken over to the newly issued refresh token.

    This property is available since Authlete 2.1.

    refreshTokenKept boolean

    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, as to how to get a new access token using a refresh token.

    This property is available since Authlete 2.0.

    supportedScopes Scope array

    Scopes supported by the service. 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". 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 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 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 and 5.1.1. Address Claim 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 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 for details.

    The value of this property is used as scopes_supported property in the OpenID Provider Metadata.

    scopeRequired boolean

    The flag to indicate whether requests that request no scope are rejected or not.

    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 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.

    This property is available since Authlete 2.1.

    idTokenDuration number

    The duration of ID tokens in seconds. This value is used to calculate the value of exp claim in an ID token.

    allowableClockSkew number

    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.

    This property is available since Authlete 2.1.

    supportedClaimTypes string array

    Claim types supported by the service. Valid values are listed in Claim Type. Note that, however, currently Authlete does not 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.

    supportedClaimLocales string array

    Claim locales that the service supports. Each element is a language tag defined in RFC 5646. For example, en-US and ja-JP. See OpenID Connect Core 1.0, 5.2. Languages and Scripts for details.

    The value of this property is used as claims_locales_supported property in the OpenID Provider Metadata.

    supportedClaims string array

    Claim names that the service supports. The standard claim names listed in OpenID Connect Core 1.0, 5.1. Standard Claim should be supported. The following is the list of standard claims.

    1. sub
    2. name
    3. given_name
    4. family_name
    5. middle_name
    6. nickname
    7. preferred_username
    8. profile
    9. picture
    10. website
    11. email
    12. email_verified
    13. gender
    14. birthdate
    15. zoneinfo
    16. locale
    17. phone_number
    18. phone_number_verified
    19. address
    20. updated_at

    The value of this property is used as claims_supported property in the OpenID Provider Metadata.

    The service may support its original claim names. See OpenID Connect Core 1.0, 5.1.2. Additional Claims.

    claimShortcutRestrictive boolean

    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.

    To strictly conform to the description below excerpted from OpenID Connect Core 1.0 Section 5.4, 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.

    This property is available since Authlete 2.1.

    jwksUri string

    The URL of the service's JSON Web Key Set 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 for details.

    The value of this property is used as jwks_uri property in the OpenID Provider Metadata.

    directJwksEndpointEnabled boolean

    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 string

    The content of the service's JSON Web Key Set document. If this property is not null in a /service/create request or a /service/update, 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 for details.

    idTokenSignatureKeyId string

    The key ID to identify a JWK used for ID token signature using an asymmetric key.

    A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See RFC 7517 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 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), this mechanism is needed.

    userInfoSignatureKeyId string

    The key ID to identify a JWK used for user info signature using an asymmetric key.

    A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See RFC 7517 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) 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 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), this mechanism is needed.

    authorizationSignatureKeyId string

    The key ID to identify a JWK used for signing authorization responses using an asymmetric key.

    Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) 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.

    This property is available since Authlete 2.1.

    userInfoEndpoint string

    The user info endpoint 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.

    directUserInfoEndpointEnabled boolean

    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 boolean

    The boolean flag which indicates whether the OAuth 2.0 Dynamic Client Registration Protocol is supported.

    This property is available since Authlete 2.1.

    registrationEndpoint string

    The registration endpoint 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.

    This property is available since Authlete 2.1.

    registrationManagementEndpoint string

    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.

    This property is available since Authlete 2.1.

    policyUri string

    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.

    tosUri string

    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.

    serviceDocumentation string

    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.

    backchannelAuthenticationEndpoint string

    The URI of backchannel authentication endpoint, which is defined in the specification of CIBA (Client Initiated Backchannel Authentication).

    This property is available since Authlete 2.1.

    supportedBackchannelTokenDeliveryModes string array

    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).

    This property is available since Authlete 2.1.

    backchannelAuthReqIdDuration number

    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.

    This property is available since Authlete 2.1.

    backchannelPollingInterval number

    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.

    This property is available since Authlete 2.1.

    backchannelUserCodeParameterSupported boolean

    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.

    This property is available since Authlete 2.1.

    backchannelBindingMessageRequiredInFapi boolean

    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.

    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.

    This property is available since Authlete 2.1.

    deviceAuthorizationEndpoint string

    The URI of the device authorization endpoint.

    Device authorization endpoint is defined in the specification of OAuth 2.0 Device Authorization Grant.

    This property is available since Authlete 2.1.

    deviceVerificationUri string

    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.

    This property is available since Authlete 2.1.

    deviceVerificationUriComplete string

    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.

    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.

    This property is available since Authlete 2.1.

    deviceFlowCodeDuration number

    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 number

    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.

    This property is available since Authlete 2.1.

    userCodeCharset string

    The character set for end-user verification codes (user_code) for Device Flow.

    This property is available since Authlete 2.1.

    userCodeLength number

    The length of end-user verification codes (user_code) for Device Flow.

    This property is available since Authlete 2.1.

    supportedTrustFrameworks string array

    Trust frameworks supported by this service. This corresponds to the trust_frameworks_supported metadata.

    This property is available since Authlete 2.2.

    supportedEvidence string array

    Evidence supported by this service. This corresponds to the evidence_supported metadata.

    This property is available since Authlete 2.2.

    supportedIdentityDocuments string array

    Identity documents supported by this service. This corresponds to the id_documents_supported metadata.

    This property is available since Authlete 2.2.

    supportedVerificationMethods string array

    Verification methods supported by this service. This corresponds to the id_documents_verification_methods_supported metadata.

    This property is available since Authlete 2.2.

    supportedVerifiedClaims string array

    Verified claims supported by this service. This corresponds to the claims_in_verified_claims_supported metadata.

    This property is available since Authlete 2.2.

    attributes Pair array

    The attributes of this service.

    This property is available since Authlete 2.2.

    Subject Type

    Constant values that correspond to the subject identifier types described in OpenID Connect Core 1.0, 8. Subject Identifier Types.

    Possible values are PUBLIC and PAIRWISE.

    Tagged Value

    A generic-purpose data structure to describe a pair of a language tag and a string. This data structure has two members, tag and value as described in the table below.

    Name Type Description
    tag string

    The language tag part.

    value string

    The value part.

    Some properties of Client such as clientNames and logoUris are represented in this data structure. See OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts for the usage of language tags in OpenID Connect.

    Service Profile

    Constant values that represent profiles that a service can support.

    Possible values are as follows.

    Value Description
    FAPI

    When this profile is enabled, it indicates the service supports Financial-grade API - Part 1: Read-Only API Security Profile and Financial-grade API - Part 2: Read and Write API Security Profile. Note that you need to enable this profile and also properly configure the service to conform the service to FAPI requirements.

    OPEN_BANKING

    When this profile is enabled, it indicates the service supports "Open Banking Security Profile". Note that you need to enable this profile and FAPI profile and also properly configure the service to conform the service to Open Banking requirements.

    Delivery Mode

    Constant values that correspond to the delivery mode values defined in the specification of CIBA (Client Initiated Backchannel Authentication).

    Possible values are PING, POLL and PUSH.

    Service Management

    /service/create API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/service/create \
    -H 'Content-Type:application/json' \
    -u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4' \
    -d '{ "serviceName": "My Service" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    Service service = new Service();
    service.setServiceName("My Service");
    
    api.createService(service);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    Service service = new Service();
    service.Name = "My Service";
    
    await api.CreateService(service);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $service = new Service();
    $service.setName("My Service");
    
    $api.createService($service);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    service = Authlete::Model::Service.new
    service.service_name = 'My Service'
    
    api.service_create(service)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    service = Service()
    service.serviceName = 'My Service'
    
    api.createService(service)
    
    conf := ...
    api := api.New(&conf)
    
    service := dto.Service{}
    service.ServiceName = "My Service"
    
    api.CreateService(&service)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const service = new Service();
    service.serviceName = 'My Service';
    
    await api.createService(service);
    

    Sample Response

    {
      "accessTokenDuration": 0,
      "accessTokenType": "Bearer",
      "allowableClockSkew": 0,
      "apiKey": 10167240235,
      "apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
      "authorizationResponseDuration": 0,
      "backchannelAuthReqIdDuration": 0,
      "backchannelBindingMessageRequiredInFapi": false,
      "backchannelPollingInterval": 0,
      "backchannelUserCodeParameterSupported": false,
      "claimShortcutRestrictive": false,
      "clientIdAliasEnabled": false,
      "clientsPerDeveloper": 0,
      "createdAt": 1612766668234,
      "deviceFlowCodeDuration": 0,
      "deviceFlowPollingInterval": 0,
      "directAuthorizationEndpointEnabled": false,
      "directIntrospectionEndpointEnabled": false,
      "directJwksEndpointEnabled": false,
      "directRevocationEndpointEnabled": false,
      "directTokenEndpointEnabled": false,
      "directUserInfoEndpointEnabled": false,
      "dynamicRegistrationSupported": false,
      "errorDescriptionOmitted": false,
      "errorUriOmitted": false,
      "idTokenDuration": 0,
      "issSuppressed": false,
      "issuer": "https://authlete.com",
      "metadata": [...],
      "missingClientIdAllowed": false,
      "modifiedAt": 1612766668234,
      "mutualTlsValidatePkiCertChain": false,
      "nbfOptional": false,
      "number": 1,
      "parRequired": false,
      "pkceRequired": false,
      "pkceS256Required": false,
      "pushedAuthReqDuration": 0,
      "refreshTokenDuration": 0,
      "refreshTokenDurationKept": false,
      "refreshTokenKept": false,
      "requestObjectRequired": false,
      "scopeRequired": false,
      "serviceName": "My Service",
      "serviceOwnerNumber": 1,
      "singleAccessTokenPerSubject": false,
      "supportedClaimTypes": [
        "NORMAL"
      ],
      "supportedDisplays": [
        "PAGE"
      ],
      "supportedGrantTypes": [
        "AUTHORIZATION_CODE",
        "IMPLICIT",
        "PASSWORD",
        "CLIENT_CREDENTIALS",
        "REFRESH_TOKEN"
      ],
      "supportedResponseTypes": [
        "NONE",
        "CODE",
        "TOKEN",
        "ID_TOKEN",
        "CODE_TOKEN",
        "CODE_ID_TOKEN",
        "ID_TOKEN_TOKEN",
        "CODE_ID_TOKEN_TOKEN"
      ],
      "supportedTokenAuthMethods": [
        "CLIENT_SECRET_BASIC"
      ],
      "tlsClientCertificateBoundAccessTokens": false,
      "traditionalRequestObjectProcessingApplied": false,
      "userCodeLength": 0
    }
    

    Create a new service.

    Request

    POST /api/service/create

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service owner.

    Request Body

    A JSON which represents a new service.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the newly created service.

    /service/get API

    Sample Request

    curl -v https://api.authlete.com/api/service/get/10167240235 \
    -u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long serviceApiKey = 10167240235;
    
    api.getService(serviceApiKey);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long serviceApiKey = 10167240235;
    
    await api.GetService(serviceApiKey);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $serviceApiKey = 10167240235;
    
    $api.getService($serviceApiKey);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    service_api_key = 10167240235
    
    api.service_get(service_api_key)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    serviceApiKey = 10167240235
    
    api.getService(serviceApiKey)
    
    conf := ...
    api := api.New(&conf)
    
    serviceApiKey := 10167240235
    
    api.GetService(serviceApiKey)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const serviceApiKey = 10167240235;
    
    await api.getService(serviceApiKey);
    

    Sample Response

    {
      "accessTokenDuration": 86400,
      "accessTokenType": "Bearer",
      "allowableClockSkew": 0,
      "apiKey": 10167240235,
      "apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
      "authorizationResponseDuration": 600,
      "backchannelAuthReqIdDuration": 600,
      "backchannelBindingMessageRequiredInFapi": false,
      "backchannelPollingInterval": 5,
      "backchannelUserCodeParameterSupported": true,
      "claimShortcutRestrictive": true,
      "clientIdAliasEnabled": false,
      "clientsPerDeveloper": 0,
      "createdAt": 1612766668234,
      "deviceFlowCodeDuration": 600,
      "deviceFlowPollingInterval": 5,
      "directAuthorizationEndpointEnabled": true,
      "directIntrospectionEndpointEnabled": true,
      "directJwksEndpointEnabled": true,
      "directRevocationEndpointEnabled": true,
      "directTokenEndpointEnabled": true,
      "directUserInfoEndpointEnabled": true,
      "dynamicRegistrationSupported": false,
      "errorDescriptionOmitted": false,
      "errorUriOmitted": false,
      "idTokenDuration": 86400,
      "issSuppressed": true,
      "issuer": "https://authlete.com",
      "metadata": [...],
      "missingClientIdAllowed": false,
      "modifiedAt": 1612788578997,
      "mutualTlsValidatePkiCertChain": false,
      "nbfOptional": true,
      "number": 1,
      "parRequired": false,
      "pkceRequired": false,
      "pkceS256Required": false,
      "pushedAuthReqDuration": 0,
      "refreshTokenDuration": 864000,
      "refreshTokenDurationKept": false,
      "refreshTokenKept": false,
      "requestObjectRequired": false,
      "scopeRequired": false,
      "serviceName": "Service 7876808783",
      "serviceOwnerNumber": 1,
      "singleAccessTokenPerSubject": false,
      "supportedBackchannelTokenDeliveryModes": [
        "POLL",
        "PING",
        "PUSH"
      ],
      "supportedClaimTypes": [
        "NORMAL"
      ],
      "supportedClaims": [
        "sub",
        "website",
        "zoneinfo",
        "email_verified",
        "birthdate",
        "address",
        "gender",
        "profile",
        "phone_number_verified",
        "preferred_username",
        "given_name",
        "middle_name",
        "locale",
        "picture",
        "updated_at",
        "name",
        "nickname",
        "phone_number",
        "family_name",
        "email"
      ],
      "supportedDisplays": [
        "PAGE",
        "POPUP",
        "TOUCH",
        "WAP"
      ],
      "supportedGrantTypes": [
        "AUTHORIZATION_CODE",
        "IMPLICIT",
        "PASSWORD",
        "CLIENT_CREDENTIALS",
        "REFRESH_TOKEN",
        "CIBA",
        "DEVICE_CODE"
      ],
      "supportedResponseTypes": [
        "NONE",
        "CODE",
        "TOKEN",
        "ID_TOKEN",
        "CODE_TOKEN",
        "CODE_ID_TOKEN",
        "ID_TOKEN_TOKEN",
        "CODE_ID_TOKEN_TOKEN"
      ],
      "supportedScopes": [
        {
          "defaultEntry": false,
          "description": "A permission to request an OpenID Provider to include the address claim in an ID Token. See OpenID Connect Core 1.0, 5.4. for details.",
          "descriptions": [
            {
              "tag": "en",
              "value": "A permission to request an OpenID Provider to include the address claim in an ID Token. See OpenID Connect Core 1.0, 5.4. for details."
            },
            ...
          ],
          "name": "address"
        },
        {...},
        {...},
        {...}
      ],
      "supportedTokenAuthMethods": [
        "CLIENT_SECRET_BASIC"
      ],
      "tlsClientCertificateBoundAccessTokens": false,
      "traditionalRequestObjectProcessingApplied": false,
      "userCodeLength": 0
    }
    

    Get information about a service.

    Request

    GET /api/service/get/{serviceApiKey}

    Authorization

    Basic Authentication with API key & API secret of a service owner.

    Path Parameters

    Name Description
    serviceApiKey

    The API key of the target service.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the service.

    /service/get/list API

    Sample Request

    curl -v https://api.authlete.com/api/service/get/list?start=0\&end=3 \
    -u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    int start = 0;
    int end = 3;
    
    api.getServiceList(start, end);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    int start = 0;
    int end = 3;
    
    await api.GetServiceList(start, end);
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = { start: 0, end: 3 }
    
    api.service_get_list(req)
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $start = 0;
    $end = 3;
    
    $api.getServiceList($start, $end);
    
    ?>
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    start = 0
    end = 3
    
    api.getServiceList(start, end)
    
    conf := ...
    api := api.New(&conf)
    
    start = 0
    end = 3
    
    api.GetServiceList(start, end)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const start = 0;
    const end = 3;
    
    await api.getServiceList(start, end);
    

    Sample Response

    {
      "end": 3,
      "start": 0,
      "services": [
        {
          "accessTokenDuration": 86400,
          "accessTokenType": "Bearer",
          "allowableClockSkew": 0,
          "apiKey": 10167240235,
          "apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
          "authorizationResponseDuration": 600,
          "backchannelAuthReqIdDuration": 600,
          "backchannelBindingMessageRequiredInFapi": false,
          "backchannelPollingInterval": 5,
          "backchannelUserCodeParameterSupported": true,
          "claimShortcutRestrictive": true,
          "clientIdAliasEnabled": false,
          "clientsPerDeveloper": 0,
          "createdAt": 1612766668234,
          "deviceFlowCodeDuration": 600,
          "deviceFlowPollingInterval": 5,
          "directAuthorizationEndpointEnabled": true,
          "directIntrospectionEndpointEnabled": true,
          "directJwksEndpointEnabled": true,
          "directRevocationEndpointEnabled": true,
          "directTokenEndpointEnabled": true,
          "directUserInfoEndpointEnabled": true,
          "dynamicRegistrationSupported": false,
          "errorDescriptionOmitted": false,
          "errorUriOmitted": false,
          "idTokenDuration": 86400,
          "issSuppressed": true,
          "issuer": "https://authlete.com",
          "metadata": [...],
          "missingClientIdAllowed": false,
          "modifiedAt": 1612788578997,
          "mutualTlsValidatePkiCertChain": false,
          "nbfOptional": true,
          "number": 1,
          "parRequired": false,
          "pkceRequired": false,
          "pkceS256Required": false,
          "pushedAuthReqDuration": 0,
          "refreshTokenDuration": 864000,
          "refreshTokenDurationKept": false,
          "refreshTokenKept": false,
          "requestObjectRequired": false,
          "scopeRequired": false,
          "serviceName": "My Service",
          "serviceOwnerNumber": 1,
          "singleAccessTokenPerSubject": false,
          "supportedBackchannelTokenDeliveryModes": [...],
          "supportedClaimTypes": [...],
          "supportedClaims": [...],
          "supportedDisplays": [...],
          "supportedGrantTypes": [...],
          "supportedResponseTypes": [...],
          "supportedScopes": [...],
          "supportedTokenAuthMethods": [...],
          "tlsClientCertificateBoundAccessTokens": false,
          "traditionalRequestObjectProcessingApplied": false,
          "userCodeLength": 0
        },
        {...},
        {...}
      ],
      "totalCount": 5
    }
    

    Get information about services.

    Request

    GET /api/service/get/list

    Authorization

    Basic Authentication with API key & API secret of a service owner.

    Query Parameters

    Name Description
    start

    Start index (inclusive) of the result set. The default value is 0. Must not be a negative number.

    end

    End index (exclusive) of the result set. The default value is 5. Must not be a negative number.

    Response

    Content-Type

    application/json

    Response body

    If successful, the response body contains the following information.

    Name Type Description
    start number

    Start index (inclusive) of the result set of the query.

    end number

    End index (exclusive) of the result set of the query.

    totalCount number

    Total number of services owned by the service owner. This doesn't mean the number of services contained in the response.

    services Service array

    An array of services.

    /service/update API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/service/update/10167240235 \
    -H 'Content-Type:application/json' \
    -u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4' \
    -d '{ "supportedTokenAuthMethods": [ "CLIENT_SECRET_BASIC", "PRIVATE_KEY_JWT" ], ... }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    // Get an existing service.
    long serviceApiKey = 10167240235;
    Service service = api.getService(serviceApiKey);
    
    // Update "supported token auth mehtods".
    service.setSupportedTokenAuthMethods(new ClientAuthMethod[] { ClientAuthMethod.CLIENT_SECRET_BASIC, ClientAuthMethod.PRIVATE_KEY_JWT });
    
    api.updateService(service);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    // Get an existing service.
    long serviceApiKey = 10167240235;
    Service service = api.GetService(serviceApiKey);
    
    // Update "supported token auth mehtods".
    service.SupportedTokenAuthMethods = new ClientAuthMethod[] { ClientAuthMethod.CLIENT_SECRET_BASIC, ClientAuthMethod.PRIVATE_KEY_JWT };
    
    await api.UpdateService(service);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    // Get an existing service.
    $serviceApiKey = 10167240235;
    $api.getService($serviceApiKey);
    
    // Update "supported token auth mehtods".
    $service.supportedTokenAuthMethods = [ ClientAuthMethod::$CLIENT_SECRET_BASIC, ClientAuthMethod::$PRIVATE_KEY_JWT ];
    
    $api.updateService($service);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    service_api_key = 10167240235
    api.service_get(service_api_key)
    
    # Update "supported token auth mehtods".
    service.supported_token_auth_methods = [ 'CLIENT_SECRET_BASIC', 'PRIVATE_KEY_JWT' ]
    
    api.service_update(service)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    # Get an existing service.
    serviceApiKey = 10167240235
    service = api.getService(serviceApiKey)
    
    # Update "supported token auth mehtods".
    service.supportedTokenAuthMethods = [ ClientAuthMethod.CLIENT_SECRET_BASIC, ClientAuthMethod.PRIVATE_KEY_JWT ]
    
    api.updateService(service)
    
    conf := ...
    api := api.New(&conf)
    
    // Get an existing service.
    serviceApiKey := 10167240235
    service, _ := api.GetService(serviceApiKey)
    
    // Update "supported token auth mehtods".
    service.SupportedTokenAuthMethods = []types.ClientAuthMethod{ types.ClientAuthMethod_CLIENT_SECRET_BASIC, types.ClientAuthMethod_PRIVATE_KEY_JWT }
    
    api.UpdateService(&service)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    // Get an existing service.
    const serviceApiKey = 10167240235;
    const service = await api.getService(serviceApiKey);
    
    // Update "supported token auth mehtods".
    service.supportedTokenAuthMethods = [ ClientAuthMethod.CLIENT_SECRET_BASIC, ClientAuthMethod.PRIVATE_KEY_JWT ];
    
    await api.updateService(service);
    

    Sample Response

    {
      "accessTokenDuration": 86400,
      "accessTokenType": "Bearer",
      "allowableClockSkew": 0,
      "apiKey": 10167240235,
      "apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
      "authorizationResponseDuration": 600,
      "backchannelAuthReqIdDuration": 600,
      "backchannelBindingMessageRequiredInFapi": false,
      "backchannelPollingInterval": 5,
      "backchannelUserCodeParameterSupported": true,
      "claimShortcutRestrictive": true,
      "clientIdAliasEnabled": false,
      "clientsPerDeveloper": 0,
      "createdAt": 1612766668234,
      "deviceFlowCodeDuration": 600,
      "deviceFlowPollingInterval": 5,
      "directAuthorizationEndpointEnabled": true,
      "directIntrospectionEndpointEnabled": true,
      "directJwksEndpointEnabled": true,
      "directRevocationEndpointEnabled": true,
      "directTokenEndpointEnabled": true,
      "directUserInfoEndpointEnabled": true,
      "dynamicRegistrationSupported": false,
      "errorDescriptionOmitted": false,
      "errorUriOmitted": false,
      "idTokenDuration": 86400,
      "issSuppressed": true,
      "issuer": "https://authlete.com",
      "metadata": [...],
      "missingClientIdAllowed": false,
      "modifiedAt": 1612788578997,
      "mutualTlsValidatePkiCertChain": false,
      "nbfOptional": true,
      "number": 1,
      "parRequired": false,
      "pkceRequired": false,
      "pkceS256Required": false,
      "pushedAuthReqDuration": 0,
      "refreshTokenDuration": 864000,
      "refreshTokenDurationKept": false,
      "refreshTokenKept": false,
      "requestObjectRequired": false,
      "scopeRequired": false,
      "serviceName": "My Service",
      "serviceOwnerNumber": 1,
      "singleAccessTokenPerSubject": false,
      "supportedBackchannelTokenDeliveryModes": [...],
      "supportedClaimTypes": [...],
      "supportedClaims": [...],
      "supportedDisplays": [...],
      "supportedGrantTypes": [...],
      "supportedResponseTypes": [...],
      "supportedScopes": [...],
      "supportedTokenAuthMethods": [
        "CLIENT_SECRET_BASIC",
        "PRIVATE_KEY_JWT"
      ],
      "tlsClientCertificateBoundAccessTokens": false,
      "traditionalRequestObjectProcessingApplied": false,
      "userCodeLength": 0
    }
    

    Update an existing service.

    Request

    POST /api/service/update/{serviceApiKey}
    PUT /api/service/update/{serviceApiKey}

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service owner.

    Path Parameters

    Name Description
    serviceApiKey

    The API key of the target service.

    Request Body

    A JSON which represents the target service.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the updated service.

    /service/delete API

    Sample Request

    curl -v -X DELETE https://api.authlete.com/api/service/delete/10167240235 \
    -u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long serviceApiKey = 10167240235;
    
    api.deleteService(serviceApiKey);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long serviceApiKey = 10167240235;
    
    await api.DeleteService(serviceApiKey);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $serviceApiKey = 57297408867;
    
    $api.deleteService($serviceApiKey);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    service_api_key = 10167240235
    
    api.service_delete(service_api_key)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    servieApiKey = 57297408867
    
    api.deleteService(servieApiKey)
    
    conf := ...
    api := api.New(&conf)
    
    servieApiKey := 57297408867
    
    api.DeleteService(servieApiKey)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const servieApiKey = 57297408867;
    
    await api.deleteService(servieApiKey);
    

    Delete a service.

    Request

    DELETE /api/service/delete/{serviceApiKey}

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service owner.

    Path Parameters

    Name Description
    serviceApiKey

    The API key of the target service.

    Client Management

    /client/create API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/client/create \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "developer": "john", "clientName": "My Client" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    Client client = new Client();
    client.setDeveloper("john");
    client.setClientName("My Client");
    
    api.createClient(client);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    Client client = new Client();
    client.Developer = "john";
    client.ClientName = "My Client";
    
    await api.CreateClient(client);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $client = new Client();
    $client.developer = "john";
    $client.clientName = "My Client";
    
    $api.createClient($client);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client = Authlete::Model::Client.new
    client.developer = 'john'
    client.client_name = 'My Client'
    
    api.client_create(client)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    client = Client()
    client.developer = 'john'
    client.clientName = 'My Client'
    
    api.createClient(client)
    
    conf := ...
    api := api.New(&conf)
    
    client := dto.Client{}
    client.Developer = "john"
    client.CientName = "My Client."
    
    api.CreateClient(client)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const client = new Client();
    client.developer = 'john';
    client.clientName = 'My Client';
    
    await api.createClient(client);
    

    Sample Response

    {
      "authTimeRequired": false,
      "bcUserCodeRequired": false,
      "clientId": 57297408867,
      "clientIdAliasEnabled": false,
      "clientName": "My Client",
      "clientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw",
      "clientType": "PUBLIC",
      "createdAt": 1612857357412,
      "defaultMaxAge": 0,
      "developer": "john",
      "dynamicallyRegistered": false,
      "idTokenSignAlg": "RS256",
      "modifiedAt": 1612857357412,
      "number": 1,
      "parRequired": false,
      "requestObjectRequired": false,
      "serviceNumber": 1,
      "subjectType": "PUBLIC",
      "tlsClientCertificateBoundAccessTokens": false,
      "tokenAuthMethod": "NONE"
    }
    

    Create a new client.

    Request

    POST /api/client/create

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    A JSON which represents a new client.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the newly created client.

    /client/get API

    Sample Request

    curl -v https://api.authlete.com/api/client/get/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    api.getClient(clientId);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    
    await api.GetClient(clientId);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    
    $api.getClient($clientId);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    
    api.client_get(client_id)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    api.getClient(clientId)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    api.GetClient(clientId)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const clientId = 57297408867;
    
    await api.getClient(clientId);
    

    Sample Response

    {
      "authTimeRequired": false,
      "bcUserCodeRequired": false,
      "clientId": 57297408867,
      "clientIdAliasEnabled": false,
      "clientName": "My Client",
      "clientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw",
      "clientType": "CONFIDENTIAL",
      "createdAt": 1612857357412,
      "defaultMaxAge": 0,
      "derivedSectorIdentifier": "https://api.authlete.com",
      "developer": "john",
      "dynamicallyRegistered": false,
      "extension": {
        "accessTokenDuration": 0,
        "refreshTokenDuration": 0,
        "requestableScopesEnabled": false
      },
      "grantTypes": [
        "AUTHORIZATION_CODE",
        "IMPLICIT",
        "PASSWORD",
        "CLIENT_CREDENTIALS",
        "REFRESH_TOKEN",
        "CIBA",
        "DEVICE_CODE"
      ],
      "idTokenSignAlg": "HS256",
      "modifiedAt": 1612857359475,
      "number": 1,
      "parRequired": false,
      "redirectUris": [
        "http://api.authlete.com/api/mock/redirection/10167240235"
      ],
      "requestObjectRequired": false,
      "responseTypes": [
        "NONE",
        "CODE",
        "TOKEN",
        "ID_TOKEN",
        "CODE_TOKEN",
        "CODE_ID_TOKEN",
        "ID_TOKEN_TOKEN",
        "CODE_ID_TOKEN_TOKEN"
      ],
      "serviceNumber": 1,
      "subjectType": "PUBLIC",
      "tlsClientCertificateBoundAccessTokens": false,
      "tokenAuthMethod": "CLIENT_SECRET_BASIC"
    }
    

    Get information about a client.

    Request

    GET /api/client/get/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    The ID of the client to be retrieved.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the client.

    /client/get/list API

    Sample Request

    curl -v https://api.authlete.com/api/client/get/list?developer=john\&start=0\&end=3 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    String developer = "john";
    int start = 0;
    int end = 3;
    
    api.getClientList(developer, start, end);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    String developer = "john";
    int start = 0;
    int end = 3;
    
    await api.GetClientList(developer, start, end);
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = { developer: 'john', start: 0, end: 3 }
    
    api.client_list_get(req)
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $developer = "john";
    $start = 0;
    $end = 3;
    
    $api.getClientList($developer, $start, $end);
    
    ?>
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    developer = 'john'
    start = 0
    end = 3
    
    api.getClientList(developer, start, end)
    
    conf := ...
    api := api.New(&conf)
    
    developer = "john"
    start = 0
    end = 3
    
    api.GetClientList(developer, start, end)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const developer = 'john';
    const start = 0;
    const end = 3;
    
    await api.getClientList(developer, start, end);
    

    Sample Response

    {
      "clients": [
        {
          "authTimeRequired": false,
          "bcUserCodeRequired": false,
          "clientId": 57297408867,
          "clientIdAliasEnabled": false,
          "clientName": "My Client",
          "clientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw",
          "clientType": "CONFIDENTIAL",
          "createdAt": 1612857357412,
          "defaultMaxAge": 0,
          "derivedSectorIdentifier": "https://api.authlete.com",
          "developer": "john",
          "dynamicallyRegistered": false,
          "extension": {...},
          "grantTypes": [...],
          "idTokenSignAlg": "HS256",
          "modifiedAt": 1612857359475,
          "number": 1,
          "parRequired": false,
          "redirectUris": [...],
          "requestObjectRequired": false,
          "responseTypes": [...],
          "serviceNumber": 1,
          "subjectType": "PUBLIC",
          "tlsClientCertificateBoundAccessTokens": false,
          "tokenAuthMethod": "CLIENT_SECRET_BASIC"
        },
        {...},
        {...}
      ],
      "end": 3,
      "start": 0,
      "totalCount": 10
    }
    

    Get information about clients.

    Request

    GET /api/client/get/list

    Authorization

    Basic Authentication with API key & API secret of a service.

    Query Parameters

    Name Description
    developer

    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.

    start

    Start index (inclusive) of the result set. The default value is 0. Must not be a negative number.

    end

    End index (exclusive) of the result set. The default value is 5. Must not be a negative number.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    developer string

    The developer of the client applications. If the request did not have developer, this property is set to null.

    start number

    Start index (inclusive) of the result set of the query.

    end number

    End index (exclusive) of the result set of the query.

    totalCount number

    Total number of clients that belong to the service. This doesn't mean the number of clients contained in the response.

    clients Client array

    An array of clients.

    /client/update API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/client/update/57297408867 \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "developer": "john", "tokenAuthMethod": "PRIVATE_KEY_JWT", ... }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    // Get an existing client.
    long clientId = 57297408867;
    Client client = api.getClient(clientId);
    
    // Update "token auth mehtod".
    client.setTokenAuthMethod(ClientAuthMethod.PRIVATE_KEY_JWT);
    
    api.updateClient(client);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    // Get an existing client.
    long clientId = 57297408867;
    Client client = api.GetClient(clientId);
    
    // Update "token auth mehtod".
    client.TokenAuthMethod = ClientAuthMethod.PRIVATE_KEY_JWT;
    
    api.UpdateClient(client);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    // Get an existing client.
    $clientId = 57297408867;
    $client = $api.getClient(clientId);
    
    // Update "token auth mehtod".
    $client.tokenAuthMethod = ClientAuthMethod::$PRIVATE_KEY_JWT;
    
    $api.updateClient($client);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    # Get an existing client.
    client_id = 57297408867
    client = api.client_get(client_id)
    
    # Update "token auth mehtod".
    client.token_auth_method = 'PRIVATE_KEY_JWT'
    
    api.client_update(client)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    # Get an existing client.
    clientId = 57297408867
    client = api.getClient(clientId)
    
    # Update "token auth mehtod".
    client.tokenAuthMethod = ClientAuthMethod.PRIVATE_KEY_JWT
    
    api.updatedClient(client)
    
    conf := ...
    api := api.New(&conf)
    
    // Get an existing client.
    clientId := 57297408867
    client, _ := api.GetClient(clientId)
    
    // Update "token auth mehtod".
    client.TokenAuthMethod = types.ClientAuthMethod_PRIVATE_KEY_JWT
    
    api.UpdateClient(&client)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    // Get an existing client.
    const clientId = 57297408867;
    const client = await api.getClient(clientId);
    
    // Update "token auth mehtod".
    client.tokenAuthMethod = ClientAuthMethod.PRIVATE_KEY_JWT;
    
    await api.updateClient(client);
    

    Sample Response

    {
      "authTimeRequired": false,
      "bcUserCodeRequired": false,
      "clientId": 57297408867,
      "clientIdAliasEnabled": false,
      "clientName": "My Client",
      "clientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw",
      "clientType": "CONFIDENTIAL",
      "createdAt": 1612857357412,
      "defaultMaxAge": 0,
      "derivedSectorIdentifier": "https://api.authlete.com",
      "developer": "john",
      "dynamicallyRegistered": false,
      "extension": {...},
      "grantTypes": [...],
      "idTokenSignAlg": "HS256",
      "modifiedAt": 1612857368345,
      "number": 1,
      "parRequired": false,
      "redirectUris": [...],
      "requestObjectRequired": false,
      "responseTypes": [...],
      "serviceNumber": 1,
      "subjectType": "PUBLIC",
      "tlsClientCertificateBoundAccessTokens": false,
      "tokenAuthMethod": "PRIVATE_KEY_JWT"
    }
    

    Update an existing client.

    Request

    POST /api/client/update/{clientId}
    PUT /api/client/update/{clientId}

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    The ID of the target client.

    Request Body

    A JSON which represents the target client.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the updated client.

    /client/delete API

    Sample Request

    curl -v -X DELETE https://api.authlete.com/api/client/delete/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    api.deleteClient(clientId);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    
    await api.DeleteClient(clientId);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    
    $api.deleteClient($clientId);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    
    api.client_delete(client_id)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    api.deleteClient(clientId)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    api.DeleteClient(clientId)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const clientId = 57297408867
    
    await api.deleteClient(clientId);
    

    Delete a client.

    Request

    DELETE /api/client/delete/{clientId}

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    The ID of the target client.

    /client/secret/refresh API

    Sample Request

    curl -v https://api.authlete.com/api/client/secret/refresh/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    api.refreshClientSecret(clientId);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    
    await api.RefreshClientSecret(clientId);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    
    $api.refreshClientSecret($clientId);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    
    api.refresh_client_secret(client_id)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    api.refreshClientSecret(clientId)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    api.RefreshClientSecret(clientId)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode": "A148001",
      "resultMessage": "[A148001] Successfully refreshed the client secret of the client (ID = 57297408867).",
      "newClientSecret": "256LJ_49MISH6pP_3WeO8I9wa2LXkZKzqsNGS6XK8srtHYYJyV0jxg-jIaA2Sa0ZA67xA4bpQFKwc94WNUZrWA",
      "oldClientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw"
    }
    

    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.

    Request

    GET /api/client/secret/refresh/{clientIdentifier}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientIdentifier

    The client ID or the client ID alias of a client.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    newClientSecret string

    The new client secret.

    oldClientSecret string

    The old client secret.

    /client/secret/update API

    Sample Request

    curl -v https://api.authlete.com/api/client/secret/update/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -H 'Content-Type:application/json' \
    -d '{ "clientSecret": "my_new_client_secret" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    String clientSecret = "my_new_client_secret";
    
    api.updateClientSecret(clientId, clientSecret);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    string clientSecret = "my_new_client_secret";
    
    await api.UpdateClientSecret(clientId, clientSecret);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    $clientSecret = "my_new_client_secret";
    
    $api.updateClientSecret($clientId, $clientSecret);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    client_secret = 'my_new_client_secret'
    
    api.update_client_secret(client_id, client_secret)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    clientSecret = 'my_new_client_secret'
    
    api.updateClientSecret(clientId, clientSecret)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    clientSecret := "my_new_client_secret"
    
    api.UpdateClientSecret(clientId, clientSecret)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode": "A149001",
      "resultMessage": "[A149001] Successfully updated the client secret of the client (ID = 57297408867).",
      "newClientSecret": "my_new_client_secret",
      "oldClientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw"
    }
    

    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.

    Request

    POST /api/client/secret/update/{clientIdentifier}

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientIdentifier

    The client ID or the client ID alias of a client.

    Request Body

    Name Description
    clientSecret

    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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    newClientSecret string

    The new client secret.

    oldClientSecret string

    The old client secret.

    /client/extension/requestable_scopes/get API

    Sample Request

    curl -v https://api.authlete.com/api/client/extension/requestable_scopes/get/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    api.getRequestableScopes(clientId);
    
    // This API is not supported yet.
    
    <?php
    
    // This API is not supported yet.
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    
    api.get_requestable_scopes(client_id)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    api.getRequestableScopes(clientId)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    api.GetRequestableScopes(clientId)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "requestableScopes": [ "openid" ]
    }
    

    Get the set of scopes that a client application is allowed to request.

    Request

    GET /api/client/extension/requestable_scopes/get/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    Query Parameters

    Name Description
    pretty

    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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    requestableScopes string array

    The set of scopes that the client application is allowed to request. This paramter will be one of the following. Details are described in the description.

    • null
    • an empty set
    • a set with at least one element

    Description

    Possible values for requestableScopes parameter in the response from this API are as follows.

    null

    When the value of requestableScopes 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.


    an empty set

    When the value of requestableScopes parameter is an empty set, it means that the client application is not allowed to request any scopes.


    a set with at least one element

    When the value of requestableScopes 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.

    /client/extension/requestable_scopes/update API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/client/extension/requestable_scopes/update/57297408867 \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "requestableScopes": [ "openid", "email" ] }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    String[] scopes = { "email", "openid" }; 
    
    api.setRequestableScopes(clientId, scope);
    
    // This API is not supported yet.
    
    <?php
    
    // This API is not supported yet.
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    scopes = [ 'email', 'openid' ] 
    
    api.set_requestable_scopes(client_id, scopes)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    scopes = [ "email", "openid" ] 
    
    api.setRequestableScopes(clientId, scopes)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    scopes := [] string{ "email", "openid" }
    
    api.setRequestableScopes(clientId, scopes)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "requestableScopes": [ "openid", "email" ]
    }
    

    Update the set of scopes that a client application is allowed to request.

    Request

    POST /api/client/extension/requestable_scopes/update/{clientId}
    PUT /api/client/extension/requestable_scopes/update/{clientId}

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    Query Parameters

    Name Description
    pretty

    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.

    Request Body

    Name Description
    requestableScopes

    A new set of scopes that the client application is allowed to request. This must be one of the following.

    • null
    • 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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    requestableScopes string array

    The set of scopes that the client application is allowed to request. This paramter will be one of the following. Details are described in the description.

    • null
    • an empty set
    • a set with at least one element

    Description

    Possible values for requestableScopes parameter in the response from this API are as follows.

    null

    When the value of requestableScopes 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.


    an empty set

    When the value of requestableScopes parameter is an empty set, it means that the client application is not allowed to request any scopes.


    a set with at least one element

    When the value of requestableScopes 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.

    /client/extension/requestable_scopes/delete API

    Sample Request

    curl -v -X DELETE https://api.authlete.com/api/client/extension/requestable_scopes/delete/57297408867 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    api.deleteRequestableScopes(clientId);
    
    // This API is not supported yet.
    
    <?php
    
    // This API is not supported yet.
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    
    api.delete_requestable_scopes(client_id)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    api.deleteRequestableScopes(clientId)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    api.deleteRequestableScopes(clientId)
    
    // This API is not supported yet.
    

    Delete the set of scopes that a client application is allowed to request.

    Request

    DELETE /api/client/extension/requestable_scopes/delete/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    /client/authorization/get/list API

    Sample Request

    curl -v https://api.authlete.com/api/client/authorization/get/list/john?start=0\&end=3 \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    ClientAuthorizationGetListRequest req = new ClientAuthorizationGetListRequest();
    req.setSubject("john");
    req.setStart(0);
    req.setEnd(3);
    
    api.getClientAuthoriztionList(req);
    
    IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
    IAuthleteApi api = new AuthleteApi(conf);
    
    ClientAuthorizationGetListRequest req = new ClientAuthorizationGetListRequest();
    req.Subject = "john";
    req.Start = 0;
    req.End = 3;
    
    await api.GetClientAuthorizationList(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new ClientAuthorizationGetListRequest();
    $req.setSubject("john");
    $req.setStart(0);
    $req.setEndt(3);
    
    $api.getClientAuthorizationList($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::ClientAuthorizationGetListRequest.new
    req.subject = 'john'
    req.start = 0
    req.end = 3
    
    api.get_client_authorization_list(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = ClientAuthorizationGetListRequest()
    req.subject = 'john'
    req.start = 0
    req.end = 3
    
    api.getClientAuthorizationList(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.ClientAuthorizationGetListRequest{}
    req.Subject = "john"
    req.Start = 0
    req.End = 3
    
    api.GetClientAuthorizationList(&req)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "clients": [
        {
          "authTimeRequired": false,
          "bcUserCodeRequired": false,
          "clientId": 57297408867,
          "clientIdAliasEnabled": false,
          "clientName": "My Client",
          "clientSecret": "Vo_CHt-t9WnAtJxdU_uyufbZCOguYylRvtGXnGxmrv06Yq9FfzJkSd2ECFd4G-pZgoJnNTAFQI55mAPLXN3LQw",
          "clientType": "CONFIDENTIAL",
          "createdAt": 1612857357412,
          "defaultMaxAge": 0,
          "derivedSectorIdentifier": "https://api.authlete.com",
          "developer": "john",
          "dynamicallyRegistered": false,
          "extension": {...},
          "grantTypes": [...],
          "idTokenSignAlg": "HS256",
          "modifiedAt": 1612857368345,
          "number": 1,
          "parRequired": false,
          "redirectUris": [...],
          "requestObjectRequired": false,
          "responseTypes": [...],
          "serviceNumber": 1,
          "subjectType": "PUBLIC",
          "tlsClientCertificateBoundAccessTokens": false,
          "tokenAuthMethod": "CLIENT_SECRET_BASIC"
        },
        {...},
        {...}
      ],
      "end": 3,
      "start": 0,
      "subject": "john",
      "totalCount": 5
    }
    

    Get a list of client applications that an end-user has authorized.

    Request

    GET /api/client/authorization/get/list
    GET /api/client/authorization/get/list/{subject}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    subject

    Unique user ID of an end-user.

    Query Parameters

    Name Description
    subject

    Unique user ID of an end-user.

    developer

    Unique ID of a client developer.

    start

    Start index of search results (inclusive). The default value is 0.

    end

    End index of search results (exclusive). The default value is 5.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    start number

    Start index of search results (inclusive).

    end number

    End index of search results (exclusive).

    developer string

    Unique ID of a client developer.

    subject string

    Unique user ID of an end-user.

    totalCount number

    Total number of clients that meet the conditions.

    clients Client array

    An array of clients.

    /client/authorization/update API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/client/authorization/update/57297408867 \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "subject": "john" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    
    ClientAuthorizationUpdateRequest req = new ClientAuthorizationUpdateRequest();
    req.setSubject("john");
    
    api.updateClientAuthorization(clientId, req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    
    ClientAuthorizationUpdateRequest req = new ClientAuthorizationUpdateRequest();
    req.Subject = "john";
    
    await api.UpdateClientAuthorization(clientId, req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    
    $req = new ClientAuthorizationUpdateRequest();
    $req.subject = "john";
    
    $api.updateClientAuthorization($clientId, $req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::ClientAuthorizationUpdateRequest.new
    req.subject = 'john'
    
    api.update_client_authorization(req) 
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    
    req = ClientAuthorizationUpdateRequest()
    req.subject = 'john'
    
    api.updateClientAuthorization(clientId, req)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    
    req := dto.ClientAuthorizationUpdateRequest{}
    req.Subject := "john"
    
    api.UpdateClientAuthorization(clientId, &req)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode": "A138001",
      "resultMessage": "[A138001] Updated 1 access token(s) issued to the client (ID = 57297408867) of the service (API Key = 10167240235)."
    }
    

    Update attributes of all existing access tokens given to a client application.

    Request

    POST /api/client/authorization/update/{clientId}

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    The ID of the target client.

    Request Body

    Name Description
    subject

    The subject (= unique identifier) of the end-user who has granted authorization to the client application.

    scopes

    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 +).

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    /client/authorization/delete API

    Sample Request

    curl -v -X DELETE https://api.authlete.com/api/client/authorization/delete/57297408867/john \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId = 57297408867;
    String subject = "john";
    
    api.deleteClientAuthoriztion(clientId, subject);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId = 57297408867;
    string subject = "john";
    
    await api.DeleteClientAuthorization(clientId, subject);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    $subject = "john";
    
    $api.deleteClientAuthoriztion($clientId, $subject);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    subject = 'john'
    
    api.delete_client_authorization(client_id, subject)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    subject = 'john'
    
    api.deleteClientAuthoriztion(clientId, subject)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    subject := "john"
    
    api.DeleteClientAuthoriztion(clientId, subject)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode": "A137001",
      "resultMessage": "[A137001] Deleted 3 access token(s) issued to the client (ID = 57297408867) of the service (API Key = 10167240235)."
    }
    

    Delete all existing access tokens issued to a client application by an end-user.

    Request

    DELETE /api/client/authorization/delete/{clientId}/{subject}
    DELETE /api/client/authorization/delete/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    subject

    Unique user ID of an end-user.

    Query Parameters

    Name Description
    subject

    Unique user ID of an end-user.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    /client/granted_scopes/get API

    Sample Request

    curl -v https://api.authlete.com/api/client/granted_scopes/get/57297408867/john \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId  = 57297408867;
    String subject = "john";
    
    api.getGrantedScopes(clientId, subject);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId  = 57297408867;
    string subject = "john";
    
    await api.GetGrantedScopes(clientId, subject); 
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    $subject = "john";
    
    $api.getGrantedScopes($clientId, $subject);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    subject = 'john'
    
    api.get_granted_scopes(client_id, subject)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    subject = 'john'
    
    api.getGrantedScopes(clientId, subject)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    subject := "john"
    
    api.GetGrantedScopes(clientId, subject)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "type": "GrantedScopesGetResponse",
      "serviceApiKey": 10167240235,
      "clientId": 57297408867,
      "subject": "john",
      "latestGrantedScopes": [ "email" ],
      "mergedGrantedScopes": [ "email", "openid" ]
    }
    

    Get the set of scopes that a user has granted to a client application.

    Request

    GET /api/client/granted_scopes/get/{clientId}/{subject}
    GET /api/client/granted_scopes/get/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    subject

    Unique user ID of an end-user.

    Query Parameters

    Name Description
    subject

    Unique user ID of an end-user.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    serviceApiKey string

    Service API key.

    clientId string

    Client ID.

    subject string

    Unique user ID of the end-user.

    latestGrantedScopes string array

    Scopes granted by the last authorization process. (See description for details.)

    mergedGrantedScopes string array

    All scopes granted so far. (See description for details.)

    Description

    Description of values for latestGrantedScopes and mergedGrantedScopes:

    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.

    []

    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" ]

    /client/granted_scopes/delete API

    Sample Request

    curl -v -X DELETE https://api.authlete.com/api/client/granted_scopes/delete/57297408867/john \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    long clientId  = 57297408867;
    String subject = "john";
    
    api.deleteGrantedScopes(clientId, subject);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    long clientId  = 57297408867;
    string subject = "john";
    
    await api.DeleteGrantedScopes(clientId, subject);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $clientId = 57297408867;
    $subject = "john";
    
    $api.deleteGrantedScopes($clientId, $subject);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    client_id = 57297408867
    subject = 'john'
    
    api.delete_granted_scopes(client_id, subject)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    clientId = 57297408867
    subject = 'john'
    
    api.deleteGrantedScopes(clientId, subject)
    
    conf := ...
    api := api.New(&conf)
    
    clientId := 57297408867
    subject := "john"
    
    api.DeleteGrantedScopes(clientId, subject)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode" : "A140002",
      "resultMessage" : "[A140002] Successfully deleted the information about scopes granted to the combination of the client (ID = 57297408867) and the subject (john)."
    }
    

    Delete the set of scopes that an end-user has granted to a client application.

    Request

    DELETE /api/client/granted_scopes/delete/{clientId}/{subject}
    DELETE /api/client/granted_scopes/delete/{clientId}

    Authorization

    Basic Authentication with API key & API secret of a service.

    Path Parameters

    Name Description
    clientId

    Client ID.

    subject

    Unique user ID of an end-user.

    Query Parameters

    Name Description
    subject

    Unique user ID of an end-user.

    Response

    Content-Type

    application/json

    Response Body

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    Description

    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.

    Authorization Endpoint

    /auth/authorization API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/authorization \
    -H 'Content-Type: application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "parameters": "response_type=code&client_id=57297408867&redirect_uri=https%3A%2F%2Fapi.authlete.com%2Fapi%2Fmock%2Fredirection%2F10167240235" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    AuthorizationRequest req = new AuthorizationRequest();
    req.setParameters(...);
    
    api.authorization(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    AuthorizationRequest req = new AuthorizationRequest();
    req.Parameters = ...;
    
    await api.Authorization(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new AuthorizationRequest();
    $req.setParameters(...);
    
    $api.authorization($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::AuthorizationRequest.new
    req.parameters = '...'
    
    api.authorization(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = AuthorizationRequest()
    req.parameters = ...
    
    api.authorization(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.AuthorizationRequest{}
    req.Parameters = ...
    
    api.Authorization(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new AuthorizationRequest();
    req.parameters = ...;
    
    await api.authorization(req);
    

    Sample Response

    {
      "resultCode": "A004001",
      "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 10167240235) for the authorization request from the client (ID = 57297408867). [response_type=code, openid=false]",
      "acrEssential": false,
      "action": "INTERACTION",
      "client": {...},
      "clientIdAliasUsed": false,
      "display": "PAGE",
      "maxAge": 0,
      "service": {...},
      "ticket": "gMEn-nd71SPWov0M2P-ddynQC330eeEK8LmttH_g6NI"
    }
    

    This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further.

    Request

    POST /api/auth/authorization

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    parameters

    Required. 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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • LOCATION
    • FORM
    • NO_INTERACTION
    • INTERACTION
    client Client

    Information about the client application which made the authorization request.

    display string

    The display mode which the client application requests by display request parameter [1]. One of the values listed in Display.

    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.

    The values listed above correspond to the values listed in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, display".

    maxAge number

    The maximum authentication age. This value comes from max_age request parameter [1], 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, max_age" for max_age request parameter, and see "OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata, default_max_age" for defaultMaxAge configuration parameter.

    service Service

    Information about the service to which the authorization request was made.

    scopes Scope array

    The scopes that the client application requests. This value comes from scope request parameter [1]. 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, 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.

    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.

    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.

    The format of address claim is not a simple string. It is described in OpenID Connect Core 1.0, 5.1.1. Address Claim.

    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.

    offline_access

    The following is an excerpt about this scope from OpenID Connect Core 1.0, 11. Offline Access.

    OPTIONAL. 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.

    uiLocales string array

    The locales that the client application presented as candidates to be used for UI. This value comes from ui_locales request parameter [1]. The format of ui_locales is a space-separated list of language tag values defined in RFC5646. See "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, 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 string array

    End-user's preferred languages and scripts for claims. This value comes from claims_locales request parameter [1]. The format of claims_locales is a space-separated list of language tag values defined in RFC5646. See "OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts" 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 string array

    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 for claims request parameter, and see OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for the special scopes.

    acrEssential boolean

    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 [1] 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 for details.

    clientIdAliasUsed boolean

    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 string array

    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 [1] or defaultAcrs configuration parameter of the client application.

    See "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, acr_values" for acr_values request parameter, and see "OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata, default_acr_values" for defaultAcrs configuration parameter.

    subject string

    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 string

    A hint about the login identifier of the end-user. The value comes from login_hint request parameter.

    prompts string array

    The list of values of prompt request parameter. Possible element values are liseted in Prompt.

    See "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, prompt" for prompt request parameter.

    lowestPrompt string

    The prompt that the UI displayed to the end-user must satisfy as the minimum level. This value comes from prompt request parameter [1] and one of the values listed in Prompt except for NONE.

    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, prompt" for prompt request parameter.

    requestObjectPayload string

    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 string

    The value of the id_token property in the claims request parameter or in the claims property in a request object.

    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 of OpenID Connect Core 1.0.

    The following is an excerpt from the specification. You can find userinfo and id_token are top-level properties.

    {
      "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.

    {
      "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 string

    The value of the userinfo property in the claims request parameter or in the claims property in a request object.

    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 of OpenID Connect Core 1.0.

    The following is an excerpt from the specification. You can find userinfo and id_token are top-level properties.

    {
      "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.

    {
      "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 string

    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.

    This property is available since Authlete 2.2.

    authorizationDetails AuthzDetails

    The authorization details. This represents the value of the authorization_details request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

    This property is available since Authlete 2.2.

    purpose string

    The purpose request parameter is defined in 8. Transaction-specific Purpose of OpenID Connect for Identity Assurance 1.0 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.

    This property is available since Authlete 2.2.

    responseContent string

    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.

    ticket string

    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.

    [1] OpenID Connect introduces request parameter and request_uri parameter as means to specify request parameters indirectly. See OpenID Connect Core 1.0, 6. Passing Request Parameters as JWTs for details.

    Description

    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.

    @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 parameter responseContent contains 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 parameter responseContent contains 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 parameter responseContent contains 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.

    A response with HTTP status of "200 OK" must be returned to the client application with an HTML which satisfies the requirements of response_mode=form_post.

    The parameter responseContent contains 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. 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.

      1. 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 response from the API to generate a response to the client application.

      2. Add the value of the maximum authentication age (which is represented in seconds) to the authentication time. The calculated value is the expiration time.

        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 response from the API to generate a response to the client application.

    3. [SUBJECT]

      Get the value of subject. 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.

      1. Compare the value of the requested subject to the current end-user.

      2. If they are equal, go to the next step ([ACRs]).

      3. 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. The value represents a list of ACRs (Authentication Context Class References) and comes from (1) acr claim in claims request parameter, (2) acr_values rquest parameter, or (3) defaultAcrs 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 supportedAcrs configuration parameter of the authorization server implementation.

      If the value of ACRs is null, go to the next step ([ISSUE]). Otherwise, follow the sub steps described below.

      1. 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 in supportedAcrs.)

      2. Compare the ACR value obtained in the above step to each element in the ACR array (acrs) in the listed order. If the ACR value was found in the array, go to the next step ([ISSUE]).

      3. If the ACR value was not found in the ACR array, in other words, if the ACR performed for the authentication of the current end-user did not match any one of the ACRs requested by the client application, get the value of acrEssential. If the boolean value 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 ([ISSUE]).

    5. [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 from the API 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 response from /auth/authorization API.

      • subject (conditionally 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 subject parameter in the response from /auth/authorization API is not null, it is necessarily identical to the value of subject parameter for /auth/authorization/issue API.

        The value of this parameter will be embedded in an ID token as the value of sub claim. When the value of subjectType configuration parameter of the client application is PAIRWISE, the value of sub claim is different from the value specified by this parameter, but PAIRWISE is not supported by Authlete yet. See 8. Subject Identifier Types 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 response from /auth/authorization API is a non-empty array and 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 response from /auth/authorization API. It is ensured that the values in claims parameter are contained in the list of supported claims which are specified by supportedClaims configuration parameter of the service.

        For example, if claims parameter lists name, email and birthdate, the value of this parameter should look like the following.

        {
          "name": "John Smith",
          "email": "john@example.com",
          "birthdate": "1974-05-06"
        }

        claimsLocales parameter in the response from /auth/authorization API 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 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 response from /auth/authorization API is null or an empty array, the value of this parameter should be null.

        See 5.1. Standard Claims 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) and (2) that claim names may be followed by a language tag (5.2. Claims Languages and Scripts). Read the specification of OpenID Connect Core 1.0 for details.

        Claim names (listed in claims parameter) that the authorization server implementation cannot understand can be ignored and their claim values do not have to be gathered.

        The claim values in this parameter will be embedded in an ID token.

      • 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). 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. 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. The format of client parameter is described in Data Type, Client.

    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.

      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. [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. Note that the specification is supported since Authlete 2.2. If the Authlete server you are using is older than 2.2, the value of authorization_details parameter in the response is always null.

    6. [CLAIMS]

      A client application may require claims of the end-user. In OpenID Connect specification, "claim" is a technical term which represents a piece of information about an end-user. claims parameter in the response from /auth/authorization API is a list of claims requested by the client aplication. The service implementation should show the end-user the claim names.

      It is ensured that the values in claims parameter are contained in the list of supported claims which are specified by supportedClaims configuration parameter of the service.

    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.)

      1. Get the value of lowestPrompt in the response from /auth/authorization API. The value is one of LOGIN, CONSENT and SELECT_ACCOUNT. The meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Note that prompts response parameter has been included in the response since August, 2016. So, you may refer to the parameter directly for better control (especially if the logic here does not meet your requirements).

      2. When the value of lowestPrompt is SELECT_ACCOUNT display a form to let the end-user select on of his/her accounts for login. If subject parameter in the response from /auth/authorization API is not null it is the end-user ID that the client expects, so it should be set to the input field for the login ID. When subject is null, loginHint may be referred to calculate the initial value of the input field.

      3. Otherwise, when the value of the lowest prompt is LOGIN, display a form to let the end-user login. If subject parameter in the response from /auth/authorization API is not null it is the end-user ID that the client expects, so it should be set to the input field for the login ID. When subject is null, loginHint may be referred to calculate the initial value of the input field.

      4. Otherwise, when the value of the lowest prompt is CONSENT, the authorization server implementation can omit a login form and use the end-user who has currently logged in the service 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.

        1. An end-user has already logged in the service.

        2. The login ID of the current end-user matches the value of subject parameter in the response from /auth/authorization API. This check should be performed only when subject is not null.

        3. The maximum authentication age, which is the value of maxAge parameter in the response from /auth/authorization API, has not passed since the current end-user logged in the service. This check should be performed only when maxAge is not 0.

          If the authorization server implementation does not manage authentication time of end-users (= cannot know when end-users logged in) and if maxAge is not 0, a login form should be displayed.

        4. The ACR (Authentication Context Class Reference) of the authentication performed for the current end-user satisfies one of the ACRs listed in acrs parameter in the response from /auth/authorization API. This check should be performed only when acrs is a non-empty array.

      In every case, the end-user authentication must satisfy one of the ACRs listed in acrs parameter when acrs is a non-empty array and acrEssential is true.

    8. [GRANT/DENY BUTTONS]

      The end-user is supposed to choose either (1) to grant authorization to the client applicationor (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 subject parameter in the response from /auth/authorization API is not null, the authorization server implementation must check whether the value matches the login ID of the authenticated user. The authorization server implementation should repeatedly show a login form until the specified 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 authentication 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. In the case of response_type=none, nothing is issued.) It 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.


    The following code snippet is an excerpt from the sample code of the authorization endpoint. This illustrates how to dispatch processing based on the value of action parameter.

    /**
     * Process the parameters of the authorization request.
     */
    private Response process(HttpServletRequest request, String parameters)
    {
        // Call Authlete's /auth/authorization API.
        AuthorizationResponse response =
            callAuthleteAuthorizationApi(parameters);
     
        // 'action' in the response denotes the next action which
        // this authorization server implementation should take.
        Action action = response.getAction();
     
        // The content of the response to the client application.
        // The format of the content varies depending on the action.
        String content = response.getResponseContent();
     
        // Dispatch according to the action.
        switch (action)
        {
            case INTERNAL_SERVER_ERROR:
                // 500 Internal Server Error
                return ResponseUtil.internalServerError(content);
     
            case BAD_REQUEST:
                // 400 Bad Request
                return ResponseUtil.badRequest(content);
     
            case LOCATION:
                // 302 Found
                return ResponseUtil.location(content);
     
            case FORM:
                // 200 OK
                return ResponseUtil.form(content);
     
            case NO_INTERACTION:
                // Process the authorization request without user interaction.
                return handleNoInteraction(response);
     
            case INTERACTION:
                // Process the authorization request with user interaction.
                return handleInteraction(request.getSession(), response);
     
            default:
                // This never happens.
                throw new InternalServerErrorException("Unknown action");
        }
    }

    /auth/authorization/fail API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/authorization \
    -H 'Content-Type: application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "ticket": "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q", "reason": "NOT_AUTHENTICATED" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    AuthorizationFailRequest req = new AuthorizationFailRequest();
    req.setTicket("c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q");
    req.setReason(AuthorizationFailRequest.Reason.NOT_AUTHENTICATED);
    
    api.authorizationFail(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    AuthorizationFailRequest req = new AuthorizationFailRequest();
    req.Ticket = "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q";
    req.Reason = AuthorizationFailReason.NOT_AUTHENTICATED;
    
    await api.AuthorizationFail(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new AuthorizationFailRequest();
    $req.setTicket("c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q");
    $req.setReason(AuthorizationFailReason.$NOT_AUTHENTICATED);
    
    $api.authorizationFail($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::AuthorizationFailRequest.new
    req.ticket = 'c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q'
    req.reason = 'NOT_AUTHENTICATED'
    
    api.authorization_fail(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = AuthorizationFailRequest()
    req.ticket = 'c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q'
    req.reason = AuthorizationFailReason.NOT_AUTHENTICATED
    
    api.authorizationFail(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.AuthorizationFailRequest{}
    req.Ticket = "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q"
    req.Reason = AuthorizationFailReason.NOT_AUTHENTICATED
    
    api.AuthorizationFail(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new AuthorizationFailRequest();
    req.ticket = 'c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q';
    req.reason = AuthorizationFailRequest.Reason.NOT_AUTHENTICATED;
    
    await api.authorizationFail(req);
    

    Sample Response

    {
      "resultCode": "A060309",
      "resultMessage": "[A060309] The authorization request failed because the end-user was not authenticated or did not exist.",
      "action": "LOCATION",
      "responseContent": "https://api.authlete.com/api/mock/redirection/10167240235?error=login_required&error_description=%5BA060309%5D+The+authorization+request+failed+because+the+end-user+was+not+authenticated+or+did+not+exist.&error_uri=https%3A%2F%2Fwww.authlete.com%2Fdocuments%2Fapis%2Fresult_codes%23A060309"
    }
    

    This API generates a content of an error authorization response that the authorization server implementation returns to the client application.

    Request

    POST /api/auth/authorization/fail

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    ticket

    Required. The ticket issued from Authlete's /auth/authorization API.

    reason

    Required. The reason of the failure of the authorization request. One of the following.

    • 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 (Available since Authlete 2.2)
    description

    Optional. The custom description about the authorization failure.

    The following are descriptions about the values of reason parameter. The description of the /auth/authorization API describes as to which reason should be used when.

    UNKNOWN

    Unknown reason.

    NOT_LOGGED_IN

    The authorization request from the client application contained prompt=none, but any end-user has logged in.

    MAX_AGE_NOT_SUPPORTED

    The authorization request from the client application contained max_age parameter with a non-zero value or the value of defaultMaxAge configuration parameter of the client application is not 0, but the service implementation cannot behave properly based the maximum authentication age value mainly because the service implementation does not manage authentication time of end-users.

    EXCEEDS_MAX_AGE

    The authorization request from the client application contained prompt=none, but the maximum authentication age (= the time specified by max_age request parameter or by defaultMaxAge configuration parameter of the client application) has passed since the time when the end-user logged in.

    DIFFERENT_SUBJECT

    The authorization request from the client application requested a specific value for sub claim, but the current end-user (in the case of prompt=none) or the end-user after the authentication is different from the specified value.

    ACR_NOT_SATISFIED

    The authorization request from the client application contained acr claim in claims request parameter and the claim was marked as essential, but the ACR (Authentication Context Class Reference) performed for the end-user does not match any of the requested ACRs.

    DENIED

    The end-user denied the authorization request from the client application.

    SERVER_ERROR

    Server error.

    NOT_AUTHENTICATED

    The end-user was not authenticated.

    ACCOUNT_SELECTION_REQUIRED

    The authorization server cannot obtain an account selection choice made by the end-user.

    CONSENT_REQUIRED

    The authorization server cannot obtain consent from the end-user.

    INTERACTION_REQUIRED

    The authorization server needs interaction with the end-user.

    INVALID_TARGET

    The requested resource is invalid, missing, unknown, or malformed. See "Resource Indicators for OAuth 2.0" for details.

    This is available since Authlete 2.2.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • LOCATION
    • FORM
    responseContent string

    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.

    Description

    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 parameter responseContent contains 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 parameter responseContent contains 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 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 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 parameter responseContent contains 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}

    The following code snippet is an excerpt from the sample code of the authorization endpoint. This illustrates how to dispatch processing based on the value of action parameter.

    /**
     * Create a response that describes the failure. This method
     * calls Authlete's {@code /auth/authorization/fail} API.
     */
    private Response createFailureResponse(String ticket, Reason reason)
    {
        // Call Authlete's /auth/authorization/fail API.
        AuthorizationFailResponse response =
            callAuthleteAuthorizationFailApi(ticket, reason);
     
        // 'action' in the response denotes the next action which
        // this authorization server implementation should take.
        AuthorizationFailResponse.Action action = response.getAction();
     
        // The content of the response to the client application.
        // The format of the content varies depending on the action.
        String content = response.getResponseContent();
     
        // Dispatch according to the action.
        switch (action)
        {
            case INTERNAL_SERVER_ERROR:
                // 500 Internal Server Error
                return ResponseUtil.internalServerError(content);
     
            case BAD_REQUEST:
                // 400 Bad Request
                return ResponseUtil.badRequest(content);
     
            case LOCATION:
                // 302 Found
                return ResponseUtil.location(content);
     
            case FORM:
                // 200 OK
                return ResponseUtil.form(content);
     
            default:
                // This never happens.
                throw new InternalServerErrorException("Unknown action");
        }
    }

    /auth/authorization/issue API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/authorization/issue \
    -H 'Content-Type: application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "ticket": "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc", "subject": "john" }'
    
    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);
    
    IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
    IAuthleteApi api = new AuthleteApi(conf);
    
    AuthorizationIssueRequest req = new AuthorizationIssueRequest();
    req.Ticket  = "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc";
    req.Subject = "john";
    
    await api.AuthorizationIssue(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new AuthorizationIssueRequest();
    $req.setTicket("FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc");
    $req.setSubject("john");
    
    $api.authorizationIssue($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::AuthorizationIssueRequest.new
    req.ticket = 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc'
    req.subject = 'john'
    
    api.authorization_issue(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = AuthorizationIssueRequest()
    req.ticket = 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc'
    req.subject = 'john'
    
    api.authorizationIssue(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.AuthorizationIssueRequest{}
    req.Ticket = "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc"
    req.Subject = "john"
    
    api.AuthorizationIssue(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new AuthorizationIssueRequest();
    req.ticket = 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc';
    req.subjec = 'john';
    
    await api.authorizationIssue(req);
    

    Sample Response

    {
      "resultCode": "A040001",
      "resultMessage": "[A040001] The authorization request was processed successfully.",
      "accessTokenDuration": 0,
      "accessTokenExpiresAt": 0,
      "action": "LOCATION",
      "authorizationCode": "_VSzpgug3OpdUymcbLYJjH1v9tE4hSPaxX_pSkxUUyk",
      "responseContent": "https://api.authlete.com/api/mock/redirection/10167240235?code=_VSzpgug3OpdUymcbLYJjH1v9tE4hSPaxX_pSkxUUyk"
    }
    

    This API generates a content of a successful authorization response that the authorization server implementation returns to the client application.

    Request

    POST /api/auth/authorization/issue

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    ticket

    The ticket issued from Authlete's /auth/authorization API.

    subject

    The subject (= a user account managed by the service) who has granted authorization to the client application.

    authTime

    The time when the authentication of the end-user occurred. Its value is the number of seconds from 1970-01-01.

    acr

    The Authentication Context Class Reference performed for the end-user authentication.

    claims

    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 for details about the format.

    properties

    Extra properties to associate with an access token and/or an authorization code. See Extra Properties for details.

    scopes

    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

    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

    JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request.

    This property is available since Authlete 2.1.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • LOCATION
    • FORM
    responseContent string

    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.

    accessToken string

    The newly issued access token. Note that an access token is issued from an authorization endpoint only when response_type contains token.

    accessTokenExpiresAt number

    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 number

    The duration of the newly issued access token in seconds.

    idToken number

    The newly issued ID token. Note that an ID token is issued from an authorization endpoint only when response_type contains id_token.

    authorizationCode string

    The newly issued authorization code. Note that an authorization code is issued only when response_type contains code.

    jwtAccessToken string

    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.

    This is available since Authlete 2.1.

    Description

    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". Authlete recommends application/json as the content type.

    The parameter responseContent contains 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 parameter responseContent contains 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 parameter responseContent contains 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}

    Token Endpoint

    /auth/token API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/token \
    -H "Content-Type: application/json" \
    -u "10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE" \
    -d '{ "parameters": "grant_type=authorization_code&code=DkKMvKzrRAsWErsWCChNX_gydqqgA55AW2OJlXmNTQI&redirect_uri=https%3A%2F%2Fapi.authlete.com%2Fapi%2Fmock%2Fredirection%2F10167240235" }'
    
    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);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    TokenRequest req = new TokenRequest();
    req.Parameters = ...;
    req.ClientId = "57297408867";
    req.ClientSecret = "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A";
    
    await api.Token(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new TokenRequest();
    $req.setParameters(...);
    $req.setClientId("57297408867");
    $req.setClientSecret("J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A");
    
    $api.token($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::TokenRequest.new
    req.parameters = '...'
    req.client_id = '57297408867'
    req.client_secret = 'J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A'
    
    api.token(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = TokenRequest()
    req.parameters = ...
    req.clientId = '57297408867'
    req.clientSecret = 'J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A'
    
    api.token(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.TokenRequest{}
    req.Parameters = ...
    req.ClientId = "57297408867"
    req.ClientSecret = "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A"
    
    api.Token(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new TokenRequest();
    req.parameters = ...;
    req.clientId = '57297408867';
    req.clientSecret = 'J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A';
    
    await api.token(req);
    

    Sample Response

    {
      "resultCode": "A050001",
      "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
      "accessToken": "rt5bUJsGfS17YCSmYGtgelMtokTLdoCmBe4VUFCk1YZ",
      "accessTokenDuration": 86400,
      "accessTokenExpiresAt": 1510647924410,
      "action": "OK",
      "clientId": 57297408867,
      "clientIdAliasUsed": false,
      "grantType": "AUTHORIZATION_CODE",
      "refreshToken": "sdQqY9Tbhsq6ZsWm1rZLgW4A3yxIk6RcgmmexHZ9BXB",
      "refreshTokenDuration": 864000,
      "refreshTokenExpiresAt": 1511425524410,
      "responseContent": "{\"scope\":null,\"expires_in\":86400,\"token_type\":\"Bearer\",\"refresh_token\":\"sdQqY9Tbhsq6ZsWm1rZLgW4A3yxIk6RcgmmexHZ9BXB\",\"access_token\":\"rt5bUJsGfS17YCSmYGtgelMtokTLdoCmBe4VUFCk1YZ\"}",
      "subject": "john"
    }
    

    This API parses request parameters of a token request and returns necessary data for the authorization server implementation to process the token request further.

    Request

    POST /api/auth/token

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    parameters

    Required. 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

    Optional. 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

    Optional. 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

    Optional. The client certificate from the MTLS of the token request from the client application.

    clientCertificatePath

    Optional. The certificate path presented by the client during client authentication. These certificates are strings in PEM format.

    properties

    Optional. Extra properties to associate with an access token. See Extra Properties for details.

    dpop

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    htm

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    htu

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INVALID_CLIENT
    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • PASSWORD
    • OK
    responseContent string

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

    username string

    The value of username request parameter in the token request. The client application must specify username when it uses Resource Owner Password Grant. 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 string

    The value of password request parameter in the token request. The client application must specify password when it uses Resource Owner Password Grant. 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 string

    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 string

    The newly issued access token.

    accessTokenExpiresAt number

    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 number

    The duration of the newly issued access token in seconds.

    refreshToken string

    The newly issued refresh token.

    refreshTokenExpiresAt number

    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 number

    The duration of the newly issued refresh token in seconds.

    idToken string

    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 string

    The grant type of the token request.

    clientId number

    The client ID.

    clientIdAlias string

    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 boolean

    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 string

    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 (grant_type=client_credentials) because it means the access token is not associated with any specific end-user.

    scopes string array

    The scopes covered by the access token.

    properties Property array

    The extra properties associated with the access token. This parameter is null when no extra property is associated with the issued access token.

    jwtAccessToken string

    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.

    This property is available since Authlete 2.1.

    resources string array

    The resources specified by the resource request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details.

    This property is available since Authlete 2.2.

    accessTokenResources string array

    The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details.

    This property is available since Authlete 2.2.

    authorizationDetails AuthzDetails

    The authorization details. This represents the value of the authorization_details request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

    When the action is PASSWORD, this property holds an array that represents the authorization_details request parameter included in the token request. In other successful cases, this property holds the authorization details associated with the issued access token.

    This property is available since Authlete 2.2.

    serviceAttributes Pair array

    The attributes of this service that the client application belongs to.

    This property is available since Authlete 2.2.

    clientAttributes Pair array

    The attributes of the client.

    This property is available since Authlete 2.2.

    Description

    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, 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.

    @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.


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

    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 contains 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 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 parameter responseContent contains 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 the value of grant_type request parameter is password. That is, the flow is Resource Owner Password Credentials.

    In this case, subject parameter and password parameter are the credentials of the resource owner (= end-user). The authorization server implementation must validate the credentials and take either of the actions below according to the validation result.

    When the credentials are valid,

    Call Authlete's /auth/token/issue API to generate an access token for the client application. The response from /auth/token/issue API contains data (an access token and others) which must be returend to the client application. Use the data to generate a response to the client application.

    When the credentials are invalid,

    Call Authlete's /auth/token/fail API with reason=INVALID_RESOURCE_OWNER_CREDENTIALS to generate an error response for the client application. The response from /auth/token/fail API contains error information which must be returned to the client application. Use the data to generate a response to the client application.

    Both /auth/token/issue API and /auth/token/fail API require ticket request parameter whose value must be the ticket in the response from Authlete's /auth/token API.


    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 parameter responseContent contains 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}

    The following code snippet is an excerpt from the sample code of the token endpoint. This illustrates how to dispatch processing based on the value of action parameter.

    private Response process(
        String parameters, String clientId, String clientSecret)
    {
        // Call Authlete's /auth/token API.
        TokenResponse response =
            callAuthleteTokenApi(parameters, clientId, clientSecret);
     
        // 'action' in the response denotes the next action which
        // this authorization server implementation should take.
        Action action = response.getAction();
     
        // The content of the response to the client application.
        String content = response.getResponseContent();
     
        // Dispatch according to the action.
        switch (action)
        {
            case INVALID_CLIENT:
                // 401 Unauthorized
                return ResponseUtil.unauthorized(content, CHALLENGE);
     
            case INTERNAL_SERVER_ERROR:
                // 500 Internal Server Error
                return ResponseUtil.internalServerError(content);
     
            case BAD_REQUEST:
                // 400 Bad Request
                return ResponseUtil.badRequest(content);
     
            case PASSWORD:
                // Process the token request whose flow is
                // "Resource Owner Password Credentials".
                return handlePassword(response);
     
            case OK:
                // 200 OK
                return ResponseUtil.ok(content);
     
            default:
                // This never happens.
                throw new InternalServerErrorException("Unknown action");
        }
    }

    /auth/token/fail API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/token/fail \
    -H "Content-Type: application/json" \
    -u "10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE" \
    -d '{ "ticket": "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c", "reason": "INVALID_RESOURCE_OWNER_CREDENTIALS" }'
    
    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);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    TokenFailRequest req = new TokenFailRequest();
    req.Ticket = "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c";
    req.Reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS;
    
    await api.TokenFail(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new TokenFailRequest();
    $req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c");
    $req.setReason(TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS);
    
    $api.tokenFail($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::TokenFailRequest.new
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'
    req.reason = 'INVALID_RESOURCE_OWNER_CREDENTIALS'
    
    api.token_fail(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = TokenFailRequest()
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'
    req.reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS
    
    api.tokenFail(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.TokenFailRequest{}
    req.Ticket = "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"
    req.Reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS
    
    api.TokenFail(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new TokenFailRequest();
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c';
    req.reason = TokenFailRequest.Reason.INVALID_RESOURCE_OWNER_CREDENTIALS;
    
    await api.tokenFail(req);
    

    Sample Response

    {
        "resultCode": "A067301",
        "resultMessage": "[A067301] The credentials (username & password) passed to the token endpoint are invalid.",
        "action": "BAD_REQUEST",
        "responseContent": "{\"error_uri\":\"https://www.authlete.com/documents/apis/result_codes#A067301\",\"error\":\"invalid_request\",\"error_description\":\"[A067301] The credentials (username & password) passed to the token endpoint are invalid.\"}"
    }
    

    This API generates a content of an error token response that the authorization server implementation returns to the client application.

    Request

    POST /api/auth/token/fail

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    ticket

    Required. The ticket issued from Authlete's /auth/token API.

    reason

    Required. The reason of the failure of the token request. One of the following.

    • UNKNOWN
    • INVALID_RESOURCE_OWNER_CREDENTIALS
    • INVALID_TARGET

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    responseContent string

    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.

    Description

    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.

    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 parameter responseContent contains 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 parameter responseContent contains 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}

    /auth/token/issue API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/token/issue \
    -H "Content-Type: application/json" \
    -u "10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE" \
    -d '{ "ticket": "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    TokenIssueRequest req = new TokenIssueRequest()
    req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c");
    
    api.tokenIssue(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    TokenIssueRequest req = new TokenIssueRequest();
    req.Ticket  = "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c";
    
    await api.TokenIssue(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new TokenIssueRequest();
    $req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c");
    
    $api.tokenIssue($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::TokenIssueRequest.new
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'
    
    api.token_issue(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = TokenIssueRequest()
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'
    
    api.tokenIssue(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.TokenIssueRequest{}
    req.Ticket = "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"
    
    api.TokenIssue(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new TokenIssueRequest();
    req.ticket = '83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c';
    
    await api.tokenIssue(req);
    

    Sample Response

    {
      "resultCode": "A054001",
      "resultMessage": "[A054001] The token request (grant_type=password) was processed successfully.",
      "accessToken": "W04RiPBuTJB6cQ-MppuVOKWAEezwU6jMx2-Q7ouSiBz",
      "accessTokenDuration": 86400,
      "accessTokenExpiresAt": 1513064337919,
      "action": "OK",
      "clientId": 57297408867,
      "clientIdAliasUsed": false,
      "refreshToken": "_zfwGRZ9cQhSm-qLGWAF4JHnk0i_Y7CNHHxf8poUtAX",
      "refreshTokenDuration": 864000,
      "refreshTokenExpiresAt": 1513841937919,
      "responseContent": "{\"scope\":null,\"expires_in\":86400,\"token_type\":\"Bearer\",\"refresh_token\":\"_zfwGRZ9cQhSm-qLGWAF4JHnk0i_Y7CNHHxf8poUtAX\",\"access_token\":\"W04RiPBuTJB6cQ-MppuVOKWAEezwU6jMx2-Q7ouSiBz\"}",
      "subject": "john"
    }
    

    This API generates a content of a successful token response that the authorization server implementation returns to the client application.

    Request

    POST /api/auth/token/issue

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    ticket

    Required. The ticket issued from Authlete's /auth/token API.

    subject

    Required. The subject (= unique identifier) of the authenticated user.

    properties

    Optional. 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. See Extra Properties for details.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • OK
    responseContent string

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

    accessToken string

    The newly issued access token. This parameter is a non-null value only when the value of action parameter is OK.

    accessTokenExpiresAt string

    The date in milliseconds since the Unix epoch (1970-01-01) at which the access token will expire.

    accessTokenDuration string

    The duration of the access token in seconds.

    refreshToken string

    The refresh token. This parameter is a non-null value only when action is OK and the service supports the refresh token flow.

    If "Refresh Token Continuous Use" configuration parameter is NO (= refreshTokenKept=false), a new refresh token is issued and the old refresh token used in the refresh token flow is invalidated. On the contrary, if the configuration parameter is YES, the refresh token itself is not refreshed.

    refreshTokenExpiresAt string

    The date in milliseconds since the Unix epoch (1970-01-01) at which the refresh token will expire.

    refreshTokenDuration string

    The duration of the refresh token in seconds.

    clientId number

    The client ID.

    clientIdAlias string

    If the client did not have an alias, this parameter is null.

    clientIdAliasUsed boolean

    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 string

    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 (grant_type=client_credentials) because it means the access token is not associated with any specific end-user.

    scopes string array

    The scopes covered by the access token.

    properties Property array

    The extra properties associated with the access token. This parameter is null when no extra property is associated with the issued access token.

    jwtAccessToken string

    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.

    This property is available since Authlete 2.1.

    accessTokenResources string array

    The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details.

    This property is available since Authlete 2.2.

    authorizationDetails AuthzDetails

    The authorization details. This represents the value of the authorization_details request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

    This property is available since Authlete 2.2.

    serviceAttributes Pair array

    The attributes of this service that the client application belongs to.

    This property is available since Authlete 2.2.

    clientAttributes Pair array

    The attributes of the client.

    This property is available since Authlete 2.2.

    Description

    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 parameter responseContent contains 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 parameter responseContent contains 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: text/html;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache
     
    {responseContent}

    Introspection Endpoint

    /auth/introspection API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/introspection \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "token": "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    IntrospectionRequest req = new IntrospectionRequest();
    req.setToken("VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI");
    
    api.introspection(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    IntrospectionRequest req = new IntrospectionRequest();
    req.Token = "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI";
    
    await api.Introspection(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new IntrospectionRequest();
    $req.setToken("VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI");
    
    $api.introspection($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::IntrospectionRequest.new
    req.token = 'VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI'
    
    api.introspection(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = IntrospectionRequest()
    req.token = 'VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI'
    
    api.introspection(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.IntrospectionRequest{}
    req.Token = "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI"
    
    api.Introspection(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new IntrospectionRequest();
    req.token = 'VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI';
    
    await api.introspection(req);
    

    Sample Response

    {
      "resultCode": "A056001",
      "resultMessage": "[A056001] The access token is valid.",
      "action": "OK",
      "clientId": 57297408867,
      "clientIdAliasUsed": false,
      "existent": true,
      "expiresAt": 1511252965000,
      "refreshable": true,
      "responseContent": "Bearer error=\"invalid_request\"",
      "subject": "john",
      "sufficient": true,
      "usable": true
    }
    

    This API gathers information about an access token.

    Request

    POST /api/auth/introspection

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    token

    Required. An access token to introspect.

    scopes

    Optional. 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

    Optional. 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

    Optional. Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method.

    This property is available since Authlete 2.0.

    dpop

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    htm

    Optional. HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the DPoP header.

    This property is available since Authlete 2.2.

    htu

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • UNAUTHORIZED
    • FORBIDDEN
    • OK
    clientId number

    The ID of the client application which is associated with the access token.

    clientIdAlias string

    The client ID alias when the authorization request or the token request for the access token was made.

    clientIdAliasUsed boolean

    The flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.

    expiresAt number

    The time at which the access token expires.

    subject subject

    The subject who is associated with the access token. This is null if the access token was issued using the flow of Client Credentials Grant.

    scopes string array

    Scopes which are associated with the access token.

    existent boolean

    true if the access token exists in the database of Authlete. This does not always mean the access token is usable.

    usable boolean

    true if the access token is usable (= exists and has not expired).

    sufficient boolean

    true if the access token covers all the required scopes.

    refreshable boolean

    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.

    responseContent string

    The content that the authorization server implementation can use as the value of WWW-Authenticate header on errors.

    properties Property array

    Extra properties associated with the access token. See Extra Properties for details.

    certificateThumbpint string

    The client certificate thumbprint used to validate the access token.

    This property is available since Authlete 2.0.

    resources string array

    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.

    This property is available since Authlete 2.2.

    accessTokenResources string array

    The target resources this proeprty holds may be the same as or different from the ones resource property holds.

    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.

    This property is available since Authlete 2.2.

    authorizationDetails AuthzDetails

    The authorization details. This represents the value of the "authorization_details" request parameter which is defined in "OAuth 2.0 Rich Authorization Requests".

    serviceAttributes Pair array

    The attributes of the service that the client application belongs to.

    This property is available since Authlete 2.2.

    clientAttributes Pair array

    The attributes of the client that the access token has been issued to.

    This property is available since Authlete 2.2.

    Description

    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's /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 parameter responseContent contains 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 (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
    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 request parameter).

    The parameter responseContent contains 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 (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 parameter responseContent contains 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 (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.

    The parameter responseContent contains 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 (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, responseContent contains a string which describes the error in the format of RFC 6750 (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.

    /auth/introspection/standard API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/introspection/standard \
    -H "Content-Type:application/json" \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "parameters":"token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    StandardIntrospectionRequest req = new StandardIntrospectionRequest();
    req.setParameters(...);
    
    api.standardIntrospection(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    StandardIntrospectionRequest req = new StandardIntrospectionRequest();
    req.Parameters = ...;
    
    await api.StandardIntrospection(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new StandardIntrospectionRequest();
    $req.setParameters(...);
    
    $api.standardIntrospection($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::StandardIntrospectionRequest.new
    req.parameters = '...'
    
    api.standard_introspection(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = StandardIntrospectionRequest()
    req.parameters = ...
    
    api.standardIntrospection(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.StandardIntrospectionRequest{}
    req.Parameters = ...
    
    api.StandardIntrospection(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new StandardIntrospectionRequest();
    req.parameters = ...;
    
    await api.standardIntrospection(req);
    

    Sample Response

    {
      "resultCode": "A145001",
      "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
      "action": "OK",
      "responseContent": "{\"exp\":1513679256,\"sub\":\"john\",\"scope\":null,\"iss\":\"https://authlete.com\",\"active\":true,\"token_type\":\"Bearer\",\"client_id\":\"57297408867\"}"
    }
    

    This API exists to help your authorization server provide its own introspection API which complies with RFC 7662 (OAuth 2.0 Token Introspection).

    Request

    POST /api/auth/introspection/standard

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    parameters

    Required. Request parameters which comply with the introspection request defined in "2.1. Introspection Request" in RFC 7662. The following is an example value of parameters.

    token=pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A&token_type_hint=access_token

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

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • OK
    responseContent string

    The response content which can be used as the entity body of the response returned to the client application.

    Description

    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.


    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 contains 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 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" 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 parameter responseContent contains 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 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 parameter responseContent contains 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.

    Revocation Endpoint

    /auth/revocation API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/revocation \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "parameters": "token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    RevocationRequest req = new RevocationRequest();
    request.setParameters(...);
    
    api.revocation(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    RevocationRequest req = new RevocationRequest();
    req.Parameters = ...;
    
    await api.Revocation(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new RevocationRequest();
    $req.setParameters(...);
    
    $api.revocation($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::RevocationRequest.new
    req.parameters = '...'
    
    api.revocation(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = RevocationRequest()
    req.parameters = ...
    
    api.revocation(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.RevocationRequest{}
    req.Parameters = ...
    
    api.Revocation(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new RevocationRequest();
    req.parameters = ...;
    
    await api.revocation(req);
    

    Sample Response

    {
      "resultCode": "A113001",
      "resultMessage": "[A113001] The token has been revoked successfully.",
      "action": "OK"
    }
    

    This API revokes access tokens and refresh tokens.

    Request

    POST /api/auth/revocation

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Required
    parameters

    Required. OAuth 2.0 token revocation request parameters which are the request parameters that the OAuth 2.0 token revocation endpoint (RFC 7009) 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

    Optional. The client ID extracted from Authorization header of the token request from the client application.

    If the token 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

    Optional. The client secret extracted from Authorization header of the token request from the client application.

    If the token 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 secret in Authorization header, the value should be extracted and set to this parameter.

    clientCertificate

    Optional. The client certificate used in the TLS connection between the client application and the revocation endpoint.

    clientCertificatePath

    Optional. The client certificate path presented by the client during client authentication.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INVALID_CLIENT
    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • OK
    responseContent string

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

    Description

    This API is supposed to be called from within the implementation of the revocation endpoint (RFC 7009) 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.


    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.

    invalid_client

    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}

    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 the HTTP status of "500 Internal Server Error".

    The parameter responseContent contains 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 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, 2.2.1. Error Response states "The error presentation conforms to the definition in Section 5.2 of [RFC 6749]."

    The parameter responseContent contains 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 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 parameter responseContent contains a 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}

    Userinfo Endpoint

    /auth/userinfo API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/userinfo \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    UserInfoRequest req = new UserInfoRequest();
    req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");
    
    api.userinfo(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    UserInfoRequest req = new UserInfoRequest();
    req.Token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI";
    
    await api.Userinfo(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new UserInfoRequest();
    $req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");
    
    $api.userinfo($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::UserInfoRequest.new
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI'
    
    api.user_info(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = UserInfoRequest()
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI'
    
    api.userinfo(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.UserInfoRequest{}
    req.Token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"
    
    api.Userinfo(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new UserInfoRequest();
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI';
    
    await api.userInfo(req);
    

    Sample Response

    {
      "resultCode": "A091001",
      "resultMessage": "[A091001] The access token presented at the userinfo endpoint is valid.",
      "action": "OK",
      "clientId": 57297408867,
      "clientIdAliasUsed": false,
      "scopes": [ "openid" ],
      "subject": "john",
      "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"
    }
    

    This API gathers information about a user.

    Request

    POST /api/auth/userinfo

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    token

    Required. An access token.

    clientCertificate

    Optional. 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 for details about the specification of certificate-bound access tokens.

    This property is available since Authlete 2.1.

    dpop

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    htm

    Optional. 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".

    This property is available since Authlete 2.2.

    htu

    Optional. 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)" for details.

    This property is available since Authlete 2.2.

    Response

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • UNAUTHORIZED
    • FORBIDDEN
    • OK
    claims string array

    The list of claims that the client application requests to be embedded in the ID token.

    clientId number

    The ID of the client application which is associated with the access token.

    clientIdAlias string

    The client ID alias when the authorization request for the access token was made.

    clientIdAliasUsed boolean

    The flag which indicates whether the client ID alias was used when the authorization request for the access token was made.

    responseContent string

    The content that the authorization server implementation can use as the value of WWW-Authenticate header on errors.

    scopes string array

    The scopes covered by the access token.

    subject string

    The subject (= resource owner's ID).

    token string

    The access token that came along with the userinfo request.

    properties Property array

    The extra properties associated with the access token.

    userInfoClaims string

    The value of the userinfo property in the claims request parameter or in the claims property in an authorization request object.

    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 of OpenID Connect Core 1.0.

    The following is an excerpt from the specification. You can find userinfo and id_token are top-level properties.

    {
      "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.

    {
      "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, this property holds the former value.

    This property is available since Authlete 2.2.

    serviceAttributes Pair array

    The attributes of the service that the client application belongs to.

    This property is available since Authlete 2.2.

    clientAttributes Pair array

    The attributes of the client that the access token has been issued to.

    This property is available since Authlete 2.2.

    Description

    This API is supposed to be called from within the implementation of the userinfo endpoint 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 the HTTP status of "500 Internal Server Error".

    The parameter responseContent returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation of your service 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 of your service 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. 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

    /auth/userinfo/issue API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/auth/userinfo/issue \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    UserInfoIssueRequest req = new UserInfoIssueRequest();
    req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");
    
    api.userinfoIssue(req);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    UserInfoIssueRequest req = new UserInfoIssueRequest();
    req.Token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI";
    
    await api.UserinfoIssue(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new UserInfoIssueRequest();
    $req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");
    
    $api.userinfoIssue($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::UserInfoIssueRequest.new
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI'
    
    api.user_info_issue(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = UserInfoIssueRequest()
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI'
    
    api.userinfoIssue(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.UserInfoIssueRequest{}
    req.Token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"
    
    api.UserinfoIssue(&req)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const req = new UserInfoIssueRequest();
    req.token = 'Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI';
    
    await api.userInfoIssue(req);
    

    Sample Response

    {
      "resultCode": "A096001",
      "resultMessage": "[A096001] An ID token was generated successfully.",
      "action": "JSON",
      "responseContent": "{\"exp\":1511600971,\"sub\":\"john\",\"aud\":[\"57297408867\"],\"iss\":\"https://authlete.com\",\"iat\":1511514571}"
    }
    

    This API generates an ID token.

    Request

    POST /api/auth/userinfo/issue

    Content-Type

    application/x-www-form-urlencoded
    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Request Body

    Name Description
    token

    Required. The access token that has been passed to the service's userinfo endpoint by the client application. In other words, the access token which was contained in the userinfo request.

    claims

    Optional. Claims in JSON format. As for the format, see "OpenID Connect Core 1.0, 5.1. Standard Claims".

    sub

    Optional. 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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains the following information.

    Name Type Description
    resultCode string

    The code which represents the result of the API call. The value is one of the result codes listed in Result Codes.

    resultMessage string

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

    action string

    The next action that the authorization server implementation should take. One of the following. Details are described in the description.

    • INTERNAL_SERVER_ERROR
    • BAD_REQUEST
    • UNAUTHORIZED
    • FORBIDDEN
    • JSON
    • JWT
    responseContent string

    The content that the authorization server implementation can use as the value of WWW-Authenticate header on errors.

    Description

    This API is supposed to be called from within the implementation of the userinfo endpoint 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 the HTTP status of "500 Internal Server Error".

    The parameter responseContent returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation of your authorization server 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 contains a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so the userinfo endpoint implementation of your authorization server 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 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 of your service 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 parameter responseContent contains 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)

    The userinfo endpoint of your service 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 parameter responseContent contains the ID token in JWT 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}

    JWK Set Endpoint

    /service/jwks/get API

    Sample Request

    curl -v https://api.authlete.com/api/service/jwks/get?pretty=true \
    -H 'Content-Type:application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    boolean pretty = true;
    boolean includePrivateKey = false;
    
    api.getServiceJwks(pretty, includePrivateKey);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    bool pretty = true;
    bool includePrivateKey = false;
    
    await api.GetServiceJwks(pretty, includePrivateKey);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $pretty = true;
    $includePrivateKey = false;
    
    $api.getServiceJwks($pretty, $includePrivateKey);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    api.get_service_jwks(pretty: true, includePrivateKeys: false)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    pretty = True
    includePrivateKey = False
    
    api.getServiceJwks(pretty, includePrivateKey)
    
    conf := ...
    api := api.New(&conf)
    
    pretty := true
    includePrivateKey := false
    
    api.GetServiceJwks(pretty, includePrivateKey)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    const pretty = true;
    const includePrivateKey = false;
    
    await api.getServiceJwks(pretty, includePrivateKey);
    

    Sample Response

    {
      "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"
        }
      ]
    }
    

    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.

    Request

    GET /api/service/jwks/get

    Authorization

    Basic Authentication with API key & API secret of a service.

    Query Parameters

    Name Description
    includePrivateKeys

    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.

    pretty

    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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the JWK Set of the service.

    Description

    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 if the service supports OpenID Connect Discovery 1.0.

    Discovery Endpoint

    /service/configuration API

    Sample Request

    curl -v https://api.authlete.com/api/service/configuration?pretty=true \
    -H "Content-Type:application/json" \
    -u "10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE"
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    api.getServiceConfiguration(true);
    
    IAuthleteConfiguration conf = ...;
    IAuthleteApi api = new AuthleteApi(conf);
    
    await api.GetServiceConfiguration(true);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $api.getServiceConfiguration(true);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    api.get_service_configuration(pretty: true)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    api.getServiceConfiguration(True)
    
    conf := ...
    api := api.New(&conf)
    
    api.GetServiceConfiguration(true)
    
    const conf: AuthleteConfiguration = ...;
    const api: AuthleteApi = new AuthleteApiImpl(conf);
    
    await api.getServiceConfiguration(true);
    

    Sample Response

    {
      "issuer": "https://authlete.com",
      "authorization_endpoint": "https://api.authlete.com/api/auth/authorization/direct/10167240235",
      "token_endpoint": "https://api.authlete.com/api/auth/token/direct/10167240235",
      "userinfo_endpoint": "https://api.authlete.com/api/auth/userinfo/direct/10167240235",
      "jwks_uri": "https://api.authlete.com/api/service/jwks/get/direct/10167240235",
      "scopes_supported": [
        "address",
        "email",
        "openid",
        "offline_access",
        "phone",
        "profile"
      ],
      "response_types_supported": [
        "none",
        "id_token",
        "code token",
        "code id_token",
        "id_token token",
        "code id_token token"
      ],
      "response_modes_supported": [
        "query",
        "fragment",
        "form_post",
        "query.jwt",
        "fragment.jwt",
        "form_post.jwt",
        "jwt"
      ],
      "grant_types_supported": [
        "authorization_code",
        "implicit",
        "password",
        "client_credentials",
        "refresh_token"
      ],
      "acr_values_supported": [
        "urn:mace:incommon:iap:silver",
        "urn:openbanking:psd2:sca",
        "urn:openbanking:psd2:ca"
      ],
      "subject_types_supported": [
        "public",
        "pairwise"
      ],
      "id_token_signing_alg_values_supported": [
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "id_token_encryption_alg_values_supported": [
        "RSA1_5",
        "RSA-OAEP",
        "RSA-OEAP-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"
      ],
      "id_token_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A192CBC-HS384",
        "A256CBC-HS512",
        "A128GCM",
        "A192GCM",
        "A256GCM"
      ],
      "userinfo_signing_alg_values_supported": [
        "none",
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "userinfo_encryption_alg_values_supported": [
        "RSA1_5",
        "RSA-OAEP",
        "RSA-OEAP-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"
      ],
      "userinfo_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A192CBC-HS384",
        "A256CBC-HS512",
        "A128GCM",
        "A192GCM",
        "A256GCM"
      ],
      "request_object_signing_alg_values_supported": [
        "none",
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "request_object_encryption_alg_values_supported": [
        "RSA1_5",
        "RSA-OAEP",
        "RSA-OEAP-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"
      ],
      "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",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "authorization_encryption_alg_values_supported": [
        "RSA1_5",
        "RSA-OAEP",
        "RSA-OEAP-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"
      ],
      "authorization_encryption_enc_values_supported": [
        "A128CBC-HS256",
        "A192CBC-HS384",
        "A256CBC-HS512",
        "A128GCM",
        "A192GCM",
        "A256GCM"
      ],
      "token_endpoint_auth_methods_supported": [
        "none",
        "client_secret_basic",
        "client_secret_post"
      ],
      "token_endpoint_auth_signing_alg_values_supported": [
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "display_values_supported": [
        "page",
        "popup",
        "touch",
        "wap"
      ],
      "claim_types_supported": [
        "normal"
      ],
      "claims_supported": [
        "sub",
        "website",
        "zoneinfo",
        "email_verified",
        "birthdate",
        "address",
        "gender",
        "profile",
        "phone_number_verified",
        "preferred_username",
        "given_name",
        "middle_name",
        "locale",
        "picture",
        "updated_at",
        "name",
        "nickname",
        "phone_number",
        "family_name",
        "email",
        "openbanking_intent_id",
        "acr"
      ],
      "claims_parameter_supported": true,
      "request_parameter_supported": true,
      "request_uri_parameter_supported": true,
      "require_request_uri_registration": true,
      "revocation_endpoint": "https://api.authlete.com/api/auth/revocation/direct/10167240235",
      "revocation_endpoint_auth_methods_supported": [],
      "revocation_endpoint_auth_signing_alg_values_supported": [
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "introspection_endpoint_auth_methods_supported": [],
      "introspection_endpoint_auth_signing_alg_values_supported": [
        "HS256",
        "HS384",
        "HS512",
        "RS256",
        "RS384",
        "RS512",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "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",
        "ES256",
        "ES384",
        "ES512",
        "PS256",
        "PS384",
        "PS512"
      ],
      "backchannel_user_code_parameter_supported": false
    }
    

    This API gathers configuration information of a service.

    Request

    GET /api/service/configuration

    Content-Type

    application/json

    Authorization

    Basic Authentication with API key & API secret of a service.

    Query Parameters

    Name Description
    pretty

    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.

    Response

    Content-Type

    application/json

    Response Body

    If successful, the response body contains a JSON which represents the configuration of the service. The detailed format is described in OpenID Provider Configuration Response

    Description

    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 must expose its configuration information in a JSON format. Details about the format are described in "3. OpenID Provider Metadata" in OpenID Connect Discovery 1.0.

    CIBA

    The following APIs are supposed to be used for implementing CIBA (Client Initiated Backchannel Authentication Flow) endpoints.

    /backchannel/authentication API

    Sample Request

    curl -v -X POST https://api.authlete.com/api/backchannel/authentication \
    -H 'Content-Type: application/json' \
    -u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
    -d '{ "parameters": "login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code", "clientId": "57297408867", "clientSecret":"J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A" }'
    
    AuthleteConfiguration conf = ...;
    AuthleteApi api = AuthleteApiFactory.create(conf);
    
    BackchannelAuthenticationRequest req = new BackchannelAuthenticationRequest();
    req.setParameters(...);
    req.setClientId("10167240235");
    req.setClientSecret("LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE");
    
    api.backchannelAuthentication(req);
    
    IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
    IAuthleteApi api = new AuthleteApi(conf);
    
    BackchannelAuthenticationRequest req = new BackchannelAuthenticationRequest();
    req.Parameters = ...;
    req.ClientId = "10167240235";
    req.ClientSecret = "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE";
    
    await api.BackchannelAuthentication(req);
    
    <?php
    
    $conf = ...;
    $api = new AuthleteApiImpl($conf);
    
    $req = new BackchannelAuthenticationRequest();
    $req.setParameters(...);
    $req.setClientId("10167240235");
    $req.setClientSecret("LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE");
    
    $api.backchannelAuthentication($req);
    
    ?>
    
    conf = ...
    api = Authlete::Api.new(conf)
    
    req = Authlete::Model::Request::BackchannelAuthenticationRequest.new
    req.parameters = '...'
    req.client_id = '10167240235'
    req.client_secret = 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' 
    
    api.backchannel_authentication(req)
    
    conf = ...
    api = AuthleteApiImpl(conf)
    
    req = BackchannelAuthenticationRequest()
    req.parameters = ...
    req.clientId = '10167240235'
    req.clientSecret = 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
    
    api.backchannelAuthentication(req)
    
    conf := ...
    api := api.New(&conf)
    
    req := dto.BackchannelAuthenticationRequest{}
    req.Parameters = ...
    req.ClientId = "10167240235"
    req.ClientSecret = "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE"
    
    api.BackchannelAuthentication(&req)
    
    // This API is not supported yet.
    

    Sample Response

    {
      "resultCode": "A179001",
      "resultMessage": "[A179001] The backchannel authentication request was processed successfully.",
      "action": "USER_IDENTIFICATION",
      "clientId": 57297408867,
      "clientIdAliasUsed": false,
      "clientName": "My Client"