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.
|
| 401 Unauthorized | All APIs may return a response with HTTP status of "401 Unauthorized" due to the following reason.
|
| 403 Forbidden | All APIs may return a response with HTTP status of "403 Forbidden" due to one of the reasons listed below.
|
Data Types
This section describes the details of data types.
Access Token
The table below lists top-level properties of the JSON object which represents an access token.
| Name | Type | Description |
|---|---|---|
accessTokenHash |
string |
The hash of the access token. |
accessTokenExpiresAt |
i64 |
The timestamp at which the access token will expire. |
refreshTokenExpiresAt |
i64 |
The timestamp at which the refresh token will expire. |
createdAt |
i64 |
The timestamp at which the access token was first created. |
lastRefreshedAt |
i64 |
The timestamp at which the access token was last refreshed using the refresh token. |
clientId |
i64 |
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. |
Application Type
The listed below are Authlete's constant values that correspond to the
values of application_type property described in
OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.
WEBNATIVE
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.
Claim Type
The listed below are Authlete's constant values that correspond to the
claim types described in
OpenID Connect Core 1.0, 5.6. Claim Types.
The supportedClaimTypes property of Service is a string array containing
values listed below.
-
NORMAL -
AGGREGATED -
DISTRIBUTED
Note that, however, currently Authlete does not provide any API to help
implementations for AGGREGATED and DISTRIBUTED.
Client Authentication Method
The table below lists Authlete's constant values that correspond to the client authentication methods at the token endpoint described in OpenID Connect Core 1.0, 9. Client Authentication.
| 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. |
PRIVATE_KEY_JWT |
This value corresponds to "private_key_jwt" described in OpenID Connect Core 1.0, 9. Client Authentication. |
RFC 6749, 2.3.
Client Authentication mentions two means for client authentication.
One is Basic
Authentication where client credentials are encoded in
Authorization header. The other is a means to embed client
credentials in the request body in
application/x-www-form-urlencoded format.
OpenID Connect Core 1.0 adds two JWT-based client authentication methods,
namely, client_secret_jwt and private_key_jwt.
The supportedTokenAuthMethods property of Service is a string array containing values
listed above. Note that, however, currently Authlete does not provide any
API to help implementations for CLIENT_SECRET_JWT and
PRIVATE_KEY_JWT.
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 class 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.
When the value of this parameter is
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 |
Client Type
The listed below are Authlete's constant values that correspond to the
client types described in
RFC 6749, 2.1.
Client Types. The clientType property of
Client has either of the values listed
below.
CONFIDENTIALPUBLIC
Client
The table below lists top-level properties of the JSON object which represents a client application.
| Name | Type | Description |
|---|---|---|
number |
i32 |
The sequential number of the client application.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
serviceNumber |
i32 |
The sequential number of the service of the client application.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
developer |
string |
The developer of the client application. It consists of at most
100 ASCII letters. This property must not be |
clientId |
i64 |
The client ID.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
clientIdAlias |
string |
The alias of the client ID. Note that the client ID alias is recognized
only when this client's |
clientIdAliasEnabled |
boolean |
Get the flag to indicate whether the client ID alias is enabled or not.
Note that Service object also has |
clientSecret |
string |
The client secret. A random 512-bit value encoded by base64url
(86 letters).
The value of this property is assigned by Authlete.
Even if the property has a value in a 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. |
clientType |
string |
The client type, either
If |
redirectUris |
URL array |
Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows.
Note that Authlete allows the
application type to be
An authorization request from a client application which has not registered any redirect URI fails unless at least all the following conditions are satisfied.
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. |
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
If |
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
If |
applicationType |
string |
The application type.
This property corresponds to |
contacts |
string array |
An array of email addresses of people responsible for the client application. Each element must consist of printable ASCII letters only and its length must not exceed 100.
This property corresponds to |
clientName |
string |
The name of the client application. At most 100 unicode letters.
If
This property corresponds to |
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. |
logoUri |
URL |
The URL pointing to the logo image of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200.
This property corresponds to |
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. |
clientUri |
URL |
The URL pointing to the home page of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200.
This property corresponds to |
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. |
policyUri |
URL |
The URL pointing to the page which describes the policy as to how end-users' profile data are used. The URL must consist of printable ASCII letters only and its length must not exceed 200.
This property corresponds to |
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. |
tosUri |
URL |
The URL pointing to the "Terms Of Service" page. The URL must consist of printable ASCII letters only and its length must not exceed 200.
This property corresponds to |
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. |
jwksUri |
URL |
The URL pointing to the JWK Set of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200. The content pointed to by the URL must be JSON which complies with the format 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.
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
OpenID Connect Dynamic Client Registration 1.0 says that
This property corresponds to |
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
This property corresponds to |
sectorIdentifier |
URL |
The sector identifier which is a URL starting with
This property corresponds to |
subjectType |
string |
The subject type that the
client application requests. Either
Because Authlete's implementation for
This property corresponds to |
idTokenSignAlg |
string |
The value of
This property corresponds to
|
idTokenEncryptionAlg |
string |
The value of
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
This property corresponds to
|
idTokenEncryptionEnc |
string |
The value of
This property corresponds to
|
userInfoSignAlg |
string |
The value of
If both
This property corresponds to
|
userInfoEncryptionAlg |
string |
The value of
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
If both
This property corresponds to
|
userInfoEncryptionEnc |
string |
The value of
This property corresponds to
|
requestSignAlg |
string |
The value of
If the value of this property is not
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
This property corresponds to
|
requestEncryptionAlg |
string |
The value of
Regardless of whether the value of this property is
This property corresponds to
|
requestEncryptionEnc |
string |
The value of
This property corresponds to
|
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. The default value is
This property corresponds to
|
tokenAuthSignAlg |
string |
The value of
This property is used only for the two JWT-based client
authentication, namely,
This property corresponds to
|
defaultMaxAge |
i32 |
The default maximum authentication age in seconds. This value is
used when an authorization request from the client application
does not have
This property corresponds to
|
defaultAcrs |
string array |
The default ACRs (Authentication Context Class References).
This value is used when an authorization request from the client
application has neither Each element must consist of printable ASCII letters only and its length must not exceed 200. |
authTimeRequired |
boolean |
This property corresponds to |
loginUri |
URL |
The URL which a third party can use to initiate a login by the
client application. The URL must start with
This property corresponds to |
requestUris |
URL array |
An array of URLs each of which points to a request object. Each URL must consist of printable ASCII letters only and its length must not exceed 200.
Authlete requires that URLs used as values for
|
description |
string |
The description about the client application. At most 200 letters in unicode. |
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. |
createdAt |
long |
The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01). |
modifiedAt |
long |
The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). |
extension |
ClientExtension |
The extended information about this client. |
tlsClientAuthSubjectDn |
string |
the string representation of the expected subject distinguished name of the
certificate this client will use in mutual TLS authentication.
See |
Display
The listed below are Authlete's constant values that correspond to the
display values described in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, display".
The supportedDisplays property of Service is a string array containing values
listed below.
PAGEPOPUPTOUCHWAP
Grant Type
The table below lists Authlete's constant values that correspond to the
values of grant_type request parameter for OAuth 2.0
token endpoint. Among the values listed here, however,
implicit cannot be used as a value for
grant_type request parameter.
It exists only as a value of supportedGrantTypes property
of Service and grantTypes
property of Client.
| 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. |
JWE Algorithm
The listed below are Authlete's 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.
-
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
The listed below are Authlete's constant values that correspond to the values of "enc" header parameter of JSON Web Encryption (JWE), which are described in JSON Web Algorithms (JWA), 5.1. "enc" (Encryption Algorithm) Header Parameter Values for JWE.
A128CBC_HS256A192CBC_HS384A256CBC_HS512A128GCMA192GCMA256GCM
JWS Algorithm
The listed below are Authlete's constant values that correspond to the values of "alg" header parameter of JSON Web Signature (JWS), which are described in JSON Web Algorithms (JWA), 3.1. "alg" (Algorithm) Header Parameter Values for JWS.
NONEHS256HS384HS512RS256RS384RS512ES256ES384ES512PS256PS384PS512
Pair
A pair of a string key and a string value.
| Name | Type | Description |
|---|---|---|
key |
string |
The key part. |
value |
string |
The value part. |
Property
Property that consists of a string key and a string value.
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 |
string |
The flag to indicate whether this property hidden from or visible to client applications.
If |
Response Type
The table below lists Authlete's valid constant values that correspond to
response_type request parameter for OAuth 2.0 authorization
endpoint. RFC 6749
defines two values, "code" and "token". Other values listed here are
added by OAuth 2.0 Multiple Response Type Encding Practices, which is a
part of Open ID Connect specification.
The supportedResponseTypes property of Service and the responseTypes
property of Client are a string array
containing values listed below.
Scope
This is 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. Letters that can be used for a scope name are %x21, %x23-5B and %x5D-7E. Put simply, they are printable ASCII letters excluding "space (%x20)", "double quotation mark (%x22)" and "backslash (%x5C)". Its length must not exceed 200. |
defaultEntry |
boolean |
|
description |
string |
OPTIONAL. The description of the scope. It is a unicode string. Its length must not exceed 200. |
Service
The table below lists top-level properties of the JSON object which represents a service.
| Name | Type | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
number |
i32 |
The sequential number of the service.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
||||||||||||||
serviceOwnerNumber |
i32 |
The sequential number of the service owner of the service.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
||||||||||||||
serviceName |
string |
The name of the service. It consists of at most 100 unicode
letters. This property must not be |
||||||||||||||
apiKey |
i64 |
The API key.
The value of this property is assigned by Authlete.
Even if the property has a value in a |
||||||||||||||
apiSecret |
string |
The API secret. A random 256-bit value encoded by base64url
(43 letters).
The value of this property is assigned by Authlete.
Even if the property has a value in a |
||||||||||||||
issuer |
URL |
The issuer identifier of the service. A URL that starts with
The value of this property is used as
|
||||||||||||||
authorizationEndpoint |
URL |
The authorization endpoint of the service. A URL that starts
with
The value of this property is used as
|
||||||||||||||
tokenEndpoint |
URL |
The token endpoint of the service. A URL that starts with
The value of this property is used as
|
||||||||||||||
revocationEndpoint |
URL |
The revocation endpoint
of the service. A URL that starts with |
||||||||||||||
userInfoEndpoint |
URL |
The user info endpoint of the service.
A URL that starts with
The value of this property is used as
|
||||||||||||||
jwksUri |
URL |
The URL of the service's JSON Web Key Set document. For example,
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 |
string |
The content of the service's JSON Web Key Set document. If this property is not
|
||||||||||||||
registrationEndpoint |
URL |
The registration endpoint of the service. A URL that starts with
The value of this property is used as
|
||||||||||||||
supportedScopes |
Scope array |
Scopes supported by the service. Authlete strongly recommends that the service register at least the following scopes.
The value of this property is used as
|
||||||||||||||
supportedResponseTypes |
string array |
Values of
The value of this property is used as
|
||||||||||||||
supportedGrantTypes |
string array |
Values of
The value of this property is used as
|
||||||||||||||
supportedAcrs |
string array |
Values of Authentication Context Class References that the service supports.
The value of this property is used as
|
||||||||||||||
supportedTokenAuthMethods |
string array |
Client authentication methods supported by the token endpoint of
the service. Valid values are listed in
Client Authentication
Method. Note that, however, currently Authlete does not
provide any API to help implementations for
The value of this property is used as
|
||||||||||||||
supportedDisplays |
string array |
Values of
The value of this property is used as
|
||||||||||||||
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
The value of this property is used as
|
||||||||||||||
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.
The value of this property is used as
The service may support its original claim names. See OpenID Connect Core 1.0, 5.1.2. Additional Claims. Note that Authlete requires that original claim names consist of only ASCII letters and its length not exceed 200. |
||||||||||||||
serviceDocumentation |
URL |
The URL of a page where documents for developers can be found.
The value of this property is used as
|
||||||||||||||
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". Authlete requires that each language tag consist of only ASCII letters and its length not exceed 30. See OpenID Connect Core 1.0, 5.2. Languages and Scripts for details.
The value of this property is used as
|
||||||||||||||
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". Authlete requires that each language tag consist of only ASCII letters and its length not exceed 30.
The value of this property is used as
|
||||||||||||||
policyUri |
URL |
The URL of the "Policy" of the service. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200.
The value of this property is used as
|
||||||||||||||
tosUri |
URL |
The URL of the "Terms Of Service" of the service. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200.
The value of this property is used as
|
||||||||||||||
authenticationCallbackEndpoint |
URL |
A Web API endpoint for user authentication which is to be prepared on the service side. It must consist of only ASCII characters and its length must not exceed 200. 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. See 'Authentication Callback' for details. |
||||||||||||||
authenticationCallbackApiKey |
string |
API key for Basic authentication at the authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100.
If the value is not empty, Authlete generates |
||||||||||||||
authenticationCallbackApiSecret |
string |
API secret for Basic authentication at the authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100. |
||||||||||||||
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 to this parameter and set Authlete server's |
||||||||||||||
snsCredentials |
string |
SNS credentials which Authlete uses to make requests to SNSes. The format is JSON. |
||||||||||||||
createdAt |
i64 |
The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01). |
||||||||||||||
modifiedAt |
i64 |
The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). |
||||||||||||||
developerAuthenticationCallbackEndpoint |
URL |
A Web API endpoint for developer authentication which is to be prepared on the server side. It must consist of only ASCII characters and its length must not exceed 200. 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. It must consist of only ASCII characters and its length must not exceed 100.
If the value is not empty, Authlete generates |
||||||||||||||
developerAuthenticationCallbackApiSecret |
string |
API secret for Basic authentication at the developer authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100. |
||||||||||||||
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 |
||||||||||||||
developerSnsCredentials |
string |
SNS credentials which Authlete uses to make requests to SNSes. The format is JSON. |
||||||||||||||
clientsPerDeveloper |
i32 |
The maximum number of client applications that a developer is allowed to create. 0 means no limit. |
||||||||||||||
directAuthorizationEndpointEnabled |
boolean |
The flag to indicate whether the direct authorization endpoint is enabled or not.
If
If |
||||||||||||||
directTokenEndpointEnabled |
boolean |
The flag to indicate whether the direct token endpoint is enabled or not.
If
If |
||||||||||||||
directRevocationEndpointEnabled |
boolean |
The flag to indicate whether the direct revocation endpoint is enabled or not.
If
If |
||||||||||||||
directUserInfoEndpointEnabled |
boolean |
The flag to indicate whether the direct userinfo endpoint is enabled or not.
If
If This feature is not implemented yet. |
||||||||||||||
directJwksEndpointEnabled |
boolean |
The flag to indicate whether the direct jwks endpoint is enabled or not.
If
If |
||||||||||||||
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
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 |
||||||||||||||
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 See RFC 7636 (Proof Key for Code Exchange by OAuth Public Clients) for details about code_challenge request parameter. |
||||||||||||||
refreshTokenKept |
boolean |
The flag to indicate whether a refresh token remains unchanged or gets renewed after its use.
If See RFC 6749 6. Refreshing an Access Token, as to how to get a new access token using a refresh token. |
||||||||||||||
errorDescriptionOmitted |
boolean |
The flag to indicate whether the
According to RFC 6749, an authorization server
may include the
If |
||||||||||||||
errorUriOmitted |
boolean |
The flag to indicate whether the
According to RFC 6749, an authorization
server may include the
If |
||||||||||||||
description |
string |
The description about the service. It consists of at most 200 unicode letters. |
||||||||||||||
accessTokenType |
string |
The access token type. This value is used as the value of
See RFC 6749 (OAuth 2.0), 7.1. Access Token Types for details. |
||||||||||||||
accessTokenDuration |
i32 |
The duration of access tokens in seconds. This value is used
as the value of |
||||||||||||||
refreshTokenDuration |
i32 |
The duration of refresh tokens in seconds. The related specifications have no requirements on refresh token duration, but Authlete sets expiration for refresh tokens. |
||||||||||||||
idTokenDuration |
i32 |
The duration of ID tokens in seconds. This value is used to
calculate the value of |
||||||||||||||
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.
|
||||||||||||||
idTokenSignatureKeyId |
boolean |
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 |
||||||||||||||
userInfoSignatureKeyId |
boolean |
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 |
Subject Type
The listed below are Authlete's constant values that correspond to the subject identifier types described in OpenID Connect Core 1.0, 8. Subject Identifier Types.
PUBLICPAIRWISE
Note that currently Authlete's implementation for PAIRWISE
is not finished, so PAIRWISE behaves in the same way as PUBLIC.
Tagged Value
TaggedValue is 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. It must consist of only ASCII letters. Its length must not exceed 30. |
value |
string |
The value part. It is a unicode string, but some client properties put more restrictive limitations such as "ASCII only". Its length must not exceed 200. |
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.
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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract request parameters that the OAuth 2.0 authorization endpoint of
// this OAuth 2.0 serever implementation received from the client application.
String parameters = extractRequestParameters();
AuthorizationRequest request = new AuthorizationRequest().setParameters(parameters);
api.authorization(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
# Extract request parameters that the OAuth 2.0 authorization endpoint of
# this OAuth 2.0 serever implementation received from the client application.
parameters = extract_request_parameters
request = Authlete::Model::Request::AuthorizationRequest.new(
parameters: parameters
)
api.authorization(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract request parameters that the OAuth 2.0 authorization endpoint of
// this OAuth 2.0 serever implementation received from the client application.
string parameters = ExtractRequestParameters();
AuthorizationRequest request = new AuthorizationRequest();
request.Parameters = parameters;
await api.Authorization(request);
Sample Response
{
"type": "authorizationResponse",
"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": {
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "Client 57297408867",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1448001847000,
"defaultMaxAge": 1209600,
"developer": "authlete_10167240235",
"grantTypes": ["AUTHORIZATION_CODE", "IMPLICIT", "PASSWORD", "CLIENT_CREDENTIALS", "REFRESH_TOKEN"],
"idTokenSignAlg": "RS256",
"modifiedAt": 1471007440000,
"number": 13,
"redirectUris": ["https://api.authlete.com/api/mock/redirection/10167240235"],
"responseTypes": ["NONE", "CODE", "TOKEN", "ID_TOKEN", "CODE_TOKEN", "CODE_ID_TOKEN", "ID_TOKEN_TOKEN", "CODE_ID_TOKEN_TOKEN"],
"serviceNumber": 2,
"subjectType": "PUBLIC",
"tokenAuthMethod": "CLIENT_SECRET_BASIC"
},
"clientIdAliasUsed": false,
"display": "PAGE",
"maxAge": 1209600,
"service": {
"accessTokenDuration": 86400,
"accessTokenType": "Bearer",
"apiKey": 10167240235,
"apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
"clientIdAliasEnabled": false,
"clientsPerDeveloper": 0,
"createdAt": 1444747657000,
"directAuthorizationEndpointEnabled": true,
"directIntrospectionEndpointEnabled": false,
"directJwksEndpointEnabled": true,
"directRevocationEndpointEnabled": true,
"directTokenEndpointEnabled": true,
"directUserInfoEndpointEnabled": true,
"errorDescriptionOmitted": false,
"errorUriOmitted": false,
"idTokenDuration": 0,
"issuer": "https://example.com",
"metadata": [...],
"modifiedAt": 1456886451000,
"number": 2,
"pkceRequired": false,
"refreshTokenDuration": 864000,
"refreshTokenKept": false,
"serviceName": "My Service",
"serviceOwnerNumber": 2,
"singleAccessTokenPerSubject": false,
"supportedClaimTypes": ["NORMAL"],
"supportedClaims": ["zoneinfo", "sub", "phone_number", "nickname", "website", "middle_name", "email_verified", "locale", "phone_number_verified", "preferred_username", "given_name", "picture", "updated_at", "address", "email", "name", "birthdate", "gender", "family_name", "profile"],
"supportedDisplays": ["PAGE", "POPUP", "TOUCH", "WAP"],
"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"],
"supportedScopes": [...],
"supportedTokenAuthMethods": ["NONE", "CLIENT_SECRET_BASIC", "CLIENT_SECRET_POST"]
},
"ticket": "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q"
}
This API parses request parameters of an authorization request and returns necessary data for the service 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.
Parameters
| Name | Required | Description |
|---|---|---|
parameters |
YES |
OAuth 2.0 authorization request parameters which are the request parameters that the OAuth 2.0 authorization endpoint of the service implementation received from the client application.
The value of |
Response
Content-Type
application/json
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. |
||||||||||||||
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
||||||||||||||
client |
Client |
Information about the client application which made the
authorization request. This may be |
||||||||||||||
display |
string |
The display mode which the client application requests
by
When the authorization request does not have
It is ensured that the value of The values listed above correspond to the values listed in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, display". |
||||||||||||||
maxAge |
integer |
The maximum authentication age. This value comes from
See "
OpenID Connect Core 1.0, 3.1.2.1. Authentication
Request, max_age" for |
||||||||||||||
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
It is ensured that scopes listed by this parameters are
contained in the list of supported scopes which are
specified by OpenID Connect defines some scope names which need to be treated specially. The table below lists the special scope names.
Note that, if |
||||||||||||||
uiLocales |
string array |
The locales that the client application presented as
candidates to be used for UI. This value comes from
It is ensured that locales listed by this parameters are
contained in the list of supported UI locales which are
specified by |
||||||||||||||
claimsLocales |
string array |
End-user's preferred languages and scripts for claims.
This value comes from
It is ensured that locales listed by this parameters are
contained in the list of supported claim locales which are
specified by |
||||||||||||||
claims |
string array |
The list of claims that the client application requests
to be embedded in the ID token. The value comes from (1)
See
OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter for |
||||||||||||||
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 |
||||||||||||||
clientIdAliasUsed |
boolean |
|
||||||||||||||
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
See "
OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, acr_values" for |
||||||||||||||
subject |
string |
The subject (= unique user ID managed by the service
implementation) that the client application expects to
grant authorization. The value comes from |
||||||||||||||
loginHint |
string |
A hint about the login identifier of the end-user.
The value comes from |
||||||||||||||
prompts |
string array |
The list of values of
See "
OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, prompt" for |
||||||||||||||
lowestPrompt |
string |
The prompt that the UI displayed to the end-user
must satisfy as the minimum level. This value comes from
When the authorization request does not contain
See "
OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, prompt" for |
||||||||||||||
responseContent |
string |
The content that the service implementation is to
return to the client application. Its format varies
depending on the value of |
||||||||||||||
ticket |
string |
A ticket issued by Authlete to the service
implementation. This is needed when the service
implementation calls either
|
[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 service implementation should check first because it denotes
the next action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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/jsonas 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
responseContentcontains 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
actionisBAD_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/jsonas 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
responseContentcontains 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
actionisLOCATION, 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
Locationheader which has a redirect URI witherrorparameter.The parameter
responseContentcontains a redirect URI witherrorparameter, so it can be used as the value ofLocationheader.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
actionisFORM, 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 containsresponse_mode=form_postas 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
responseContentcontains 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
actionisNO_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 containsprompt=none.The service must follow the steps described below.
-
[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/failAPI withreason=NOT_LOGGED_INand use the response from the API to generate a response to the client application. -
[MAX_AGE]
Get the value of
maxAgeparameter. The value represents the maximum authentication age which has come frommax_agerequest parameter ordefaultMaxAgeconfiguration parameter of the client application. If the value is 0, go to the next step ([SUBJECT]). Otherwise, follow the sub steps described below.-
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/failAPI withreason=MAX_AGE_NOT_SUPPORTEDand use the response from the API to generate a response to the client application. -
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/failAPI withreason=EXCEEDS_MAX_AGEand use the response from the API to generate a response to the client application.
-
-
[SUBJECT]
Get the value of
subject. The value represents an end-user who the client application expects to grant authorization. If the value isnull, go to the next step ([ACRs]). Otherwise, follow the sub steps described below.-
Compare the value of the requested subject to the current end-user.
-
If they are equal, go to the next step ([ACRs]).
-
If they are not equal, call Authlete's
/auth/authorization/failAPI withreason=DIFFERENT_SUBJECTand use the response from the API to generate a response to the client application.
-
-
[ACRs]
Get the value of
acrs. The value represents a list of ACRs (Authentication Context Class References) and comes from (1)acrclaim inclaimsrequest parameter, (2)acr_valuesrquest parameter, or (3)defaultAcrsconfiguration parameter of the client application.It is ensured that all the ACRs in
acrsare supported by the service implementation. In other words, it is ensured that all the ACRs are listed insupportedAcrsconfiguration parameter of the service implementation.If the value of ACRs is
null, go to the next step ([ISSUE]). Otherwise, follow the sub steps described below.-
Get the ACR performed for the authentication of the current end-user. Note that this value is managed not by Authlete but by the service implementation. (If the service implementation cannot handle ACRs, it should not have listed ACRs in
supportedAcrs.) -
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]). -
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 istrue, call Authlete's/auth/authorization/failAPI withreason=ACR_NOT_SATISFIEDand use the response from the API to generate a response to the client application. Otherwise, go to the next step ([ISSUE]).
-
-
[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/issueAPI. The API requires the following parameters. Prepare these parameters and call/auth/authorization/issueAPI 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 ofticketcontained in the response from/auth/authorizationAPI. -
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 service 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
subjectparameter in the response from/auth/authorizationAPI is notnull, it is necessarily identical to the value ofsubjectparameter for/auth/authorization/issueAPI.The value of this parameter will be embedded in an ID token as the value of
subclaim. When the value ofsubjectTypeconfiguration parameter of the client application isPAIRWISE, the value ofsubclaim is different from the value specified by this parameter, butPAIRWISEis 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
subrequest parameter to adjust the value of thesubclaim in an ID token. See the description of thesubrequest 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_timeclaim. -
acr(optional)This parameter represents the ACR (Authentication Context Class Reference) which the authentication of the end-user satisfies. When
acrsin the response from/auth/authorizationAPI is a non-empty array andacrEssentialistrue, the value of this parameter must be one of the array elements. Otherwise, evennullis allowed. The value of this parameter will be embedded in an ID token as the value ofacrclaim. -
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 service 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 service implementation is required to gather are listed in
claimsparameter in the response from/auth/authorizationAPI. It is ensured that the values inclaimsparameter are contained in the list of supported claims which are specified bysupportedClaimsconfiguration parameter of the service.For example, if
claimsparameter listsname,emailandbirthdate, the value of this parameter should look like the following.{ "name": "John Smith", "email": "john@example.com", "birthdate": "1974-05-06" }claimsLocalesparameter in the response from/auth/authorizationAPI lists the end-user's preferred languages and scripts, ordered by preference. WhenclaimsLocalesparameter is a non-empty array, its elements should be taken into account when the service 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_localesparameter, 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
claimsparameter in the response from/auth/authorizationAPI isnullor an empty array, the value of this parameter should benull.See 5.1. Standard Claims of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the service 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
claimsparameter) that the service 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
propertiesparameter is accepted only when Content-Type of the request isapplication/json, so don't useapplication/x-www-form-urlencodedfor 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/authorizationAPI checks whether the request has come along withpromptrequest parameter and the value includes"consent". However, note that the implementation of Authlete's/auth/authorization/issueAPI does not perform such checking if"offline_access"scope is added via this scopes parameter. -
sub(optional)The value of the
subclaim in an ID token. If the value of this request parameter is not empty, it is used as the value of thesubclaim. Otherwise, the value of thesubjectrequest parameter is used as the value of thesubclaim. The main purpose of this parameter is to hide the actual value of the subject from client applications.Note that even if this
subparameter is not empty, the value of thesubjectrequest parameter is used as the value of the subject which is associated with the access token.
-
-
[END-USER AUTHENTICATION]
INTERACTION-
When the value of
actionisINTERACTION, 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.
-
[DISPLAY MODE]
The response from
/auth/authorizationAPI hasdisplayparameter. It is one ofPAGE(default),POPUP,TOUCHandWAPThe meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Basically, the service implementation should display the UI which is suitable for the display mode, but it is okay for the service implementation to "attempt to detect the capabilities of the User Agent and present an appropriate display."It is ensured that the value of
displayis one of the supported display modes which are specified bysupportedDisplaysconfiguration parameter of the service. -
[UI LOCALE]
The response from
/auth/authorizationAPI hasuiLocalesparameter. It it is notnull, it lists language tag values (such asfr-CA,ja-JPanden) 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
uiLocalesare contained in the list of supported UI locales which are specified bysupportedUiLocalesconfiguration parameter of the service. -
[CLIENT INFORMATION]
The service implementation should show information about the client application to the end-user. The information is embedded in
clientparameter in the response from/auth/authorizationAPI. The format ofclientparameter is described in Data Type, Client. -
[SCOPES]
A client application requires authorization for specific permissions. In OAuth 2.0 specification, "scope" is a technical term which represents a permission.
scopesparameter in the response from/auth/authorizationAPI 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
scopesparameter are contained in the list of supported scopes which are specified bysupportedScopesconfiguration parameter of the service. -
[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.
claimsparameter in the response from/auth/authorizationAPI 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
claimsparameter are contained in the list of supported claims which are specified bysupportedClaimsconfiguration parameter of the service. -
[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.)
-
Get the value of
lowestPromptin the response from/auth/authorizationAPI. The value is one ofLOGIN,CONSENTandSELECT_ACCOUNT. The meanings of the values are described in 3.1.2.1. Authentication Request of OpenID Connect Core 1.0. Note thatpromptsresponse 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). -
When the value of
lowestPromptisSELECT_ACCOUNTdisplay a form to let the end-user select on of his/her accounts for login. Ifsubjectparameter in the response from/auth/authorizationAPI is notnullit is the end-user ID that the client expects, so it should be set to the input field for the login ID. Whensubjectisnull,loginHintmay be referred to calculate the initial value of the input field. -
Otherwise, when the value of the lowest prompt is
LOGIN, display a form to let the end-user login. Ifsubjectparameter in the response from/auth/authorizationAPI is notnullit is the end-user ID that the client expects, so it should be set to the input field for the login ID. Whensubjectisnull,loginHintmay be referred to calculate the initial value of the input field. -
Otherwise, when the value of the lowest prompt is
CONSENT, the service 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.-
An end-user has already logged in the service.
-
The login ID of the current end-user matches the value of
subjectparameter in the response from/auth/authorizationAPI. This check should be performed only whensubjectis not null. -
The maximum authentication age, which is the value of
maxAgeparameter in the response from/auth/authorizationAPI, has not passed since the current end-user logged in the service. This check should be performed only whenmaxAgeis not 0.If the service implementation does not manage authentication time of end-users (= cannot know when end-users logged in) and if
maxAgeis not 0, a login form should be displayed. -
The ACR (Authentication Context Class Reference) of the authentication performed for the current end-user satisfies one of the ACRs listed in
acrsparameter in the response from/auth/authorizationAPI. This check should be performed only whenacrsis a non-empty array.
-
In every case, the end-user authentication must satisfy one of the ACRs listed in
acrsparameter whenacrsis a non-empty array andacrEssentialistrue. -
-
[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
subjectparameter in the response from/auth/authorizationAPI is notnull, the service implementation must check whether the value matches the login ID of the authenticated user. The service 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/failAPI withreason=DENIEDand 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 service 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/issueAPI. Read [ISSUE] written above in the description for the case ofaction=NO_INTERACTION. -
[DISPLAY MODE]
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 service 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract the ticket issued by '/auth/authorization' API.
String ticket = extractTicket();
AuthorizationFailRequest request = new AuthorizationFailRequest()
.setTicket(ticket)
.setReason(AuthorizationFailRequest.Reason.NOT_AUTHENTICATED)
;
api.authorizationFail(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE
)
# Extract the ticket issued by '/auth/token' API.
ticket = extract_ticket
# The reason of the failure of the token request.
reason = 'NOT_AUTHENTICATED'
request = Authlete::Model::Request::AuthorizationFailRequest.new(
ticket: ticket,
reason: reason
)
api.authorization_fail(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract the ticket issued by '/auth/authorization' API.
string ticket = ExtractTicket();
AuthorizationFailRequest request = new AuthorizationFailRequest();
request.Ticket = ticket;
reqeust.Reason = AuthorizationFailReason.NOT_AUTHENTICATED;
await api.AuthorizationFail(request);
Sample Response
{
"type": "authorizationFailResponse",
"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 service 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.
Parameters
| Name | Required | Description |
|---|---|---|
ticket |
YES |
The ticket issued from Authlete's |
reason |
YES |
The reason of the failure of the authorization request. One of the following.
|
description |
NO |
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_ageparameter with a non-zero value or the value ofdefaultMaxAgeconfiguration 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 bymax_agerequest parameter or bydefaultMaxAgeconfiguration 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
subclaim, but the current end-user (in the case ofprompt=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
acrclaim inclaimsrequest 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.
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation is to
return to the client application. Its format varies
depending on the value of |
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
service implementation should check first because it denotes the next
action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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/jsonas the content type.The parameter
responseContentcontains 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
actionisBAD_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/jsonas the content type.The parameter
responseContentcontains 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
actionisLOCATION, it means that the response to the client application must be "302 Found" withLocationheader.The parameter
responseContentcontains a redirect URI witherrorparameter, so it can be used as the value ofLocationheader.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
actionisFORM, 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 containedresponse_mode=form_post.The parameter
responseContentcontains 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 service 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract the ticket issued by '/auth/authorization' API.
String ticket = extractTicket();
// Get the subject (= unique identifier) of the end-user.
String subject = getSubject();
AuthorizationIssueRequest request = new AuthorizationIssueRequest()
.setTicket(ticket)
.setSubject(subject)
;
api.authorizationIssue(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
# Extract the ticket issued by '/auth/authorization' API.
ticket = extract_ticket
# Get the subject (= unique identifier) of the end-user.
subject = get_subject
request = Authlete::Model::Request::AuthorizationIssueRequest.new(
ticket: ticket,
reason: subject
)
api.authorization_issue(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract the ticket issued by '/auth/authorization' API.
string ticket = ExtractTicket();
// Get the subject (= unique identifier) of the end-user.
string subject = GetSubject();
AuthorizationIssueRequest request = new AuthorizationIssueRequest();
request.Ticket = ticket;
request.Subject = subject;
await api.AuthorizationIssue(request);
Sample Response
{
"type": "authorizationIssueResponse",
"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 service 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.
Parameters
| Name | Required | Description |
|---|---|---|
ticket |
YES |
The ticket issued from Authlete's |
subject |
YES |
The subject (= a user account managed by the service) who has granted authorization to the client application. |
authTime |
NO |
The time when the authentication of the end-user occurred. Its value is the number of seconds from 1970-01-01. |
acr |
NO |
The Authentication Context Class Reference performed for the end-user authentication. |
claims |
NO |
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 |
NO |
Extra properties to associate with an access token and/or an authorization code. See Extra Properties for details. |
scopes |
NO |
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 |
NO |
The value of the |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation is to
return to the client application. Its format varies
depending on the value of |
accessToken |
string |
The newly issued access token. Note that an access token is issued
from an Authorization Endpoint only when |
accessTokenExpiresAt |
integer |
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 |
integer |
The duration of the newly issued access token in seconds. |
idToken |
string |
The newly issued ID token. Note that an ID token is issued from
an Authorization Endpoint only when |
authorizationCode |
string |
The newly issued authorization code. Note that an authorization code
is issued only when |
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
service implementation should check first because it denotes the next
action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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/jsonas the content type.The parameter
responseContentcontains 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
actionisBAD_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/jsonas the content type.The parameter
responseContentcontains 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
actionisLOCATION, it means that the response to the client application must be "302 Found" withLocationheader.The parameter
responseContentcontains 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 ofLocationheader.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
actionisFORM, 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 containedresponse_mode=form_post.The parameter
responseContentcontains 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract request parameters that the OAuth 2.0 token endpoint of
// this OAuth 2.0 serever implementation received from the client application.
String parameters = extractRequestParameters();
TokenRequest request = new TokenRequest().setParameters(parameters);
api.token(request);
require 'authlete'
api = Authlete::Api.new(
host: "https://api.authlete.com",
service_api_key: "10167240235",
service_api_secret: "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE"
)
# Extract request parameters that the OAuth 2.0 token endpoint of
# this OAuth 2.0 serever implementation received from the client application.
parameters = extract_request_parameters
request = Authlete::Model::Request::TokenRequest.new(
parameters: parameters
)
api.token(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract request parameters that the OAuth 2.0 token endpoint of
// this OAuth 2.0 serever implementation received from the client application.
string parameters = ExtractRequestParameters();
TokenRequest request = new TokenRequest();
request.Parameters(parameters);
await api.Token(request);
Sample Response
{
"type": "tokenResponse",
"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 service 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.
Parameters
| Name | Required | Description |
|---|---|---|
parameters |
YES |
OAuth 2.0 token request parameters which are the request parameters that the OAuth 2.0 Token Endpoint of the service implementation received from the client application.
The value of |
clientId |
NO |
The client ID extracted from
If the Token Endpoint of the service implementation
supports Basic Authentication as a means of
client authentication, and the request from the
client application contained its client ID in
|
clientSecret |
NO |
The client secret extracted from
If the Token Endpoint of the service implementation
supports Basic Authentication as a means of
client authentication, and the request from the
client application contained its client secret in
|
properties |
NO |
Extra properties to associate with an access token. See Extra Properties for details. |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation is to return to the client application. Its format is JSON. |
username |
string |
The value of
This parameter has a value only if the value of
|
password |
string |
The value of
This parameter has a value only if the value of
|
ticket |
string |
The ticket which is necessary to call Authlete's
This parameter has a value only if the value of
|
accessToken |
string |
The newly issued access token. |
accessTokenExpiresAt |
integer |
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 |
integer |
The duration of the newly issued access token in seconds. |
refreshToken |
string |
The newly issued refresh token. |
refreshTokenExpiresAt |
integer |
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 |
integer |
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 |
grantType |
string |
The grant type of the token request. |
clientId |
i64 |
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 |
clientIdAliasUsed |
boolean |
The flag which indicates whether 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 |
scopes |
string array |
The scopes covered by the access token. |
properties |
string |
The extra properties associated with the access token. This parameter is |
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 service 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 service implementation should take. According to the value
of action, the service implementation must take the
steps described below.
INVALID_CLIENT-
When the value of
actionisINVALID_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 aboutinvalid_clientshown 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
responseContentcontains 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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
actionisBAD_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
responseContentcontains 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
actionisPASSWORD, it means that the request from the client application is valid and the value ofgrant_typerequest parameter ispassword. That is, the flow is Resource Owner Password Credentials.In this case,
subjectparameter andpasswordparameter are the credentials of the resource owner (= end-user). The service 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/issueAPI to generate an access token for the client application. The response from/auth/token/issueAPI 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/failAPI withreason=INVALID_RESOURCE_OWNER_CREDENTIALSto generate an error response for the client application. The response from/auth/token/failAPI 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/issueAPI and/auth/token/failAPI requireticketrequest parameter whose value must be theticketin the response from Authlete's/auth/tokenAPI. OK-
When the value of
actionisOK, 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
responseContentcontains 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 service 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract the ticket issued by '/auth/token' API.
String ticket = extractRequestTicket();
TokenFailRequest request = new TokenFailRequest()
.setTicket(ticket)
.setReason(TokenFailRequest.Reason.INVALID_RESOURCE_OWNER_CREDENTIALS)
;
api.tokenFail(request);
require 'authlete'
api = Authlete::Api.new(
host: "https://api.authlete.com",
service_api_key: "10167240235",
service_api_secret: "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE"
)
# Extract the ticket issued by '/api/token' API.
ticket = extract_ticket
# The reason of the failure of the authorization request.
reason = 'INVALID_RESOURCE_OWNER_CREDENTIALS'
request = Authlete::Model::Request::TokenFailRequest.new(
ticket: ticket,
reason: reason
)
api.token_fail(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract the ticket issued by '/auth/token' API.
string ticket = ExtractTicket();
TokenFailRequest request = new TokenFailRequest();
request.Ticket = ticket;
reqeust.Reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS;
await api.TokenFail(request);
Sample Response
{
"type": "tokenFailResponse",
"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 service implementation returns to the client application. This API is used only for Resource Owner Password Credentials Grant.
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.
Parameters
| Name | Required | Description |
|---|---|---|
ticket |
YES |
The ticket issued from Authlete's |
reason |
YES |
The reason of the failure of the token request.
|
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation is to
return to the client application. Its format varies
depending on the value of |
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
service implementation should check first because it denotes the next
action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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
actionisBAD_REQUEST, it means that Authlete's/auth/token/failAPI 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
responseContentcontains 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract the ticket issued by '/auth/token' API.
String ticket = extractTicket();
TokenIssueRequest request = new TokenIssueRequest().setTicket(ticket);
api.tokenIssue(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
# Extract the ticket issued by '/auth/token' API.
ticket = extract_ticket
request = Authlete::Model::Request::TokenIssueRequest.new(ticket: ticket)
api.token_issue(request)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract the ticket issued by '/auth/token' API.
string ticket = ExtractTicket();
TokenIssueRequest request = new TokenIssueRequest();
request.Ticket = ticket;
await api.TokenIssue(request);
Sample Response
{
"type": "tokenIssueResponse",
"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 service implementation returns to the client application. This API is used only for Resource Owner Password Credentials Grant.
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.
Parameters
| Name | Required | Description |
|---|---|---|
ticket |
YES |
The ticket issued from Authlete's |
properties |
NO |
Extra properties to associate with a newly created access
token. Note that |
subject |
YES |
The subject (= unique identifier) of the authenticated user. |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation is to return to the client application. Its format is JSON. |
accessToken |
string |
The newly issued access token. This parameter is a
|
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
If "Refresh Token Continuous Use" configuration parameter is |
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 |
i64 |
The client ID. |
clientIdAlias |
string |
If the client did not have an alias, this parameter is |
clientIdAliasUsed |
boolean |
The flag which indicates whether 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 |
scopes |
string array |
The scopes covered by the access token. |
properties |
string |
The extra properties associated with the access token. This parameter is |
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
service implementation should check first because it denotes the next
action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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
actionisOK, it means that Authlete's/auth/token/issueAPI 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
responseContentcontains 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}
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", "description": "This is My Service." }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
Service service = new Service()
.setServiceName("My Service")
.setDescription("This is My Service.")
;
api.createService(service);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_owner_api_key: 9503564165,
service_owner_api_secret: 'cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
)
request = Authlete::Model::Service.new(
service_name: 'My Service',
description: 'This is My Service.'
)
api.service_create(service)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
Service service = new Service();
service.Name = "My Service";
service.Description = "This is My Service.";
await api.CreateService(service);
Sample Response
{
"accessTokenDuration": 0,
"accessTokenType": "Bearer",
"apiKey": 10167240235,
"apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
"clientIdAliasEnabled": false,
"clientsPerDeveloper": 0,
"createdAt": 1510652454389,
"description": "This is My Service.",
"directAuthorizationEndpointEnabled": false,
"directIntrospectionEndpointEnabled": false,
"directJwksEndpointEnabled": false,
"directRevocationEndpointEnabled": false,
"directTokenEndpointEnabled": false,
"directUserInfoEndpointEnabled": false,
"errorDescriptionOmitted": false,
"errorUriOmitted": false,
"idTokenDuration": 0,
"issuer": "https://authlete.com",
"metadata": [...],
"modifiedAt": 1510652454389,
"number": 1034,
"pkceRequired": false,
"refreshTokenDuration": 0,
"refreshTokenKept": false,
"serviceName": "My Service",
"serviceOwnerNumber": 2,
"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"]
}
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.
Parameters
A JSON which represents a new service. The detailed format is described in Service.
Response
Content-Type
application/json
Parameters
A JSON which represents the newly created service. The detailed format is described in Service. The pair of API key & API secret of the service is embedded in the entity body of the response.
/service/get API
Sample Request
curl -v https://api.authlete.com/api/service/get/10167240235 \
-u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long serviceApiKey = 10167240235;
api.getService(serviceApiKey);
require 'authlete'
api = Authlete::Api.new(
host: "https://api.authlete.com",
service_owner_api_key: 9503564165,
service_owner_api_secret: 'cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
)
service_api_key = 10167240235
api.service_get(service_api_key)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long serviceApiKey = 10167240235;
await api.GetService(serviceApiKey);
Sample Response
{
"accessTokenDuration": 0,
"accessTokenType": "Bearer",
"apiKey": 10167240235,
"apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
"clientIdAliasEnabled": false,
"clientsPerDeveloper": 0,
"createdAt": 1510652454389,
"description": "This is My Service.",
"directAuthorizationEndpointEnabled": false,
"directIntrospectionEndpointEnabled": false,
"directJwksEndpointEnabled": false,
"directRevocationEndpointEnabled": false,
"directTokenEndpointEnabled": false,
"directUserInfoEndpointEnabled": false,
"errorDescriptionOmitted": false,
"errorUriOmitted": false,
"idTokenDuration": 0,
"issuer": "https://authlete.com",
"metadata": [...],
"modifiedAt": 1510652454389,
"number": 1034,
"pkceRequired": false,
"refreshTokenDuration": 0,
"refreshTokenKept": false,
"serviceName": "My Service",
"serviceOwnerNumber": 2,
"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"]
}
Get information about a service.
Request
GET /api/service/get/{serviceApiKey}
Authorization
Basic Authentication with API key & API secret of a service owner.
Parameters
| Name | Required | Description |
|---|---|---|
serviceApiKey |
YES |
The API key of the service to be retrieved. |
Response
Content-Type
application/json
Parameters
A JSON which represents the service. The detailed format is described in 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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
int start = 0;
int end = 3;
api.getServiceList(start, end);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_owner_api_key: 9503564165,
service_owner_api_secret: 'cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
)
parameters = { start: 0, end: 3 }
api.service_get_list(parameters)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
int start = 0;
int end = 3;
await api.GetServiceList(start, end);
Sample Response
{
"start": 0,
"end": 3,
"totalCount": 3,
"services": [
{
"accessTokenDuration": 0,
"accessTokenType": "Bearer",
"apiKey": 10167240235,
"apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
"clientIdAliasEnabled": false,
"clientsPerDeveloper": 0,
"createdAt": 1510652454389,
"description": "This is My Service.",
"directAuthorizationEndpointEnabled": false,
"directIntrospectionEndpointEnabled": false,
"directJwksEndpointEnabled": false,
"directRevocationEndpointEnabled": false,
"directTokenEndpointEnabled": false,
"directUserInfoEndpointEnabled": false,
"errorDescriptionOmitted": false,
"errorUriOmitted": false,
"idTokenDuration": 0,
"issuer": "https://authlete.com",
"metadata": [...],
"modifiedAt": 1510652454389,
"number": 1034,
"pkceRequired": false,
"refreshTokenDuration": 0,
"refreshTokenKept": false,
"serviceName": "My Service",
"serviceOwnerNumber": 2,
"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"]
},
{...},
{...}
]
}
Get information about services.
Request
GET /api/service/get/list
Authorization
Basic Authentication with API key & API secret of a service owner.
Parameters
| Name | Required | Description |
|---|---|---|
start |
NO |
The start index (inclusive) of the result set. The default value is 0. Must not be a negative number. |
end |
NO |
The end index (exclusive) of the result set. The default value is 5. Must not be a negative number. |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
start |
i32 |
The start index (inclusive) of the result set of the query. |
end |
i32 |
The end index (exclusive) of the result set of the query. |
totalCount |
i32 |
The total number of services owned by the service owner. This is different from 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 '{ "description": "This is My Updated Test Service.", "serviceName": "My Updated Test Service" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
Service service = new Service()
.setApiKey(10167240235)
.setServiceName("My Updated Service")
.setDescription("This is My Updated Service.")
;
api.updateService(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_owner_api_key: 9503564165,
service_owner_api_secret: 'cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
)
# The API key of the service to be updated.
service_api_key = 10167240235
service = Authlete::Model::Request::Service.new(
service_name: 'My Updated Service',
description: 'This is My Updated Service.'
)
api.service_update(service_api_key, service)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
Service service = new Service();
service.ApiKey = 10167240235;
service.Name = "My Updated Service";
service.Description = "This is My Updated Service.";
await api.UpdateService(service);
Sample Response
{
"accessTokenDuration": 0,
"accessTokenType": "Bearer",
"apiKey": 10167240235,
"apiSecret": "LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE",
"clientIdAliasEnabled": false,
"clientsPerDeveloper": 0,
"createdAt": 1510652454389,
"description": "This is My Updated Service.",
"directAuthorizationEndpointEnabled": false,
"directIntrospectionEndpointEnabled": false,
"directJwksEndpointEnabled": false,
"directRevocationEndpointEnabled": false,
"directTokenEndpointEnabled": false,
"directUserInfoEndpointEnabled": false,
"errorDescriptionOmitted": false,
"errorUriOmitted": false,
"idTokenDuration": 0,
"issuer": "https://authlete.com",
"metadata": [...],
"modifiedAt": 1510738648894,
"number": 1034,
"pkceRequired": false,
"refreshTokenDuration": 0,
"refreshTokenKept": false,
"serviceName": "My Updated Service",
"serviceOwnerNumber": 2,
"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"]
}
Update an existing service.
Request
POST /api/service/update
PUT /api/service/update
Content-Type
application/json
Authorization
Basic Authentication with API key & API secret of a service owner.
Parameters
A JSON which represents the service to be updated. The detailed format is described in Service.
Response
Content-Type
application/json
Parameters
A JSON which represents the updated service. The detailed format is described in Service.
/service/delete API
Sample Request
curl -v -X DELETE https://api.authlete.com/api/service/delete/4656860419614 \
-u '9503564165:cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// The API key of the service to be deleted.
long serviceApiKey = 10167240235;
api.deleteService(serviceApiKey);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_owner_api_key: 9503564165,
service_owner_api_secret: 'cxRpzPEkvqYbDu14gpCVKi_p6kMQvcW-lBRi7IfWLG4'
)
# The API key of the service to be deleted.
service_api_key = 10167240235
api.service_delete(service_api_key)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// The API key of the service to be deleted.
long serviceApiKey = 10167240235;
await api.DeleteService(serviceApiKey);
Sample Response
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.
Parameters
| Name | Required | Description |
|---|---|---|
serviceApiKey |
YES |
The API key of the service to be deleted. |
Response
Content-Type
application/json
Parameters
A JSON which represents the deleted service. The detailed format is described in 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", "description": "This is My Client." }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
Client client = new Client()
.setClientName("My Client")
.setDescription("This is My Client.")
;
api.createClient(client);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
client = Authlete::Model::Client.new(
client_name: 'My Client',
description: 'This is My Client.'
)
api.client_create(client)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
Client client = new Client();
client.Name = "My Client";
client.Description = "This is My Client.";
await api.CreateClient(client);
Sample Response
{
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "My Client",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1510911877097,
"defaultMaxAge": 0,
"description": "This is My Client.",
"developer": "john",
"idTokenSignAlg": "RS256",
"modifiedAt": 1510911877097,
"number": 1344,
"serviceNumber": 1043,
"subjectType": "PUBLIC",
"tokenAuthMethod": "CLIENT_SECRET_BASIC"
}
Create a new client.
Request
POST /api/client/create
Content-Type
application/json
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
A JSON which represents a new client. The detailed format is described in Client.
Response
Content-Type
application/json
Parameters
A JSON which represents the newly created client. The detailed format is described in Client. The pair of client ID & client secret of the client is embedded in the entity body of the response.
/client/get API
Sample Request
curl -v https://api.authlete.com/api/client/get/57297408867 \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
api.getClient(clientId);
require 'authlete'
api = Authlete::Api.new(
host: "https://api.authlete.com",
service_api_key: 4694807187524,
service_api_secret: "mtztVQ1EDKMO3TozWJr22I2RRv8q4HlE-F9QibsHifQ"
)
client_id = 5774937767487
api.client_get(client_id)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
await api.GetClient(clientId);
Sample Response
{
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "My Client",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1510911877097,
"defaultMaxAge": 0,
"description": "This is My Client.",
"developer": "john",
"idTokenSignAlg": "RS256",
"modifiedAt": 1510911877097,
"number": 1344,
"serviceNumber": 1043,
"subjectType": "PUBLIC",
"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.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
The ID of the client to be retrieved. |
Response
Content-Type
application/json
Parameters
A JSON which represents the client. The detailed format is described in Client.
/client/get/list API
Sample Request
curl -v https://api.authlete.com/api/client/get/4656860419614?start=0\&end=3 \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
int start = 0;
int end = 3;
api.getClientList(start, end);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
parameters = { start: 0, end: 3 }
api.client_get_list(parameters)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
int start = 0;
int end = 3;
await api.GetClientList(start, end);
Sample Response
{
"clients": [
{
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "My Client",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1510911877097,
"defaultMaxAge": 0,
"description": "This is My Client.",
"developer": "john",
"idTokenSignAlg": "RS256",
"modifiedAt": 1510911877097,
"number": 1344,
"serviceNumber": 1043,
"subjectType": "PUBLIC",
"tokenAuthMethod": "CLIENT_SECRET_BASIC"
},
{...},
{...}
],
"end": 3,
"start": 0,
"totalCount": 3
}
Get information about services.
Request
GET /api/client/get/list
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
start |
NO |
The start index (inclusive) of the result set. The default value is 0. Must not be a negative number. |
end |
NO |
The end index (exclusive) of the result set. The default value is 5. Must not be a negative number. |
developer |
NO |
The developer of client applications. The default value
is |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
start |
i32 |
The start index (inclusive) of the result set of the query. |
end |
i32 |
The end index (exclusive) of the result set of the query. |
developer |
String |
The developer of the client applications. If the request
did not have |
totalCount |
i32 |
The total number of clients that belong to the service. This is different from 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", "clientName": "My Updated Client", "description": "This is My Updated Client." }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
Client client = new Client()
.setClientName("My Updated Client")
.setDescription("This is My Updated Client.")
;
api.updateClient(client);
require 'authlete'
api = Authlete::Api.new(
host: "https://api.authlete.com",
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
client = Authlete::Model::Client.new(
client_name: "My Updated Client",
description: "This is My Updated Client."
)
api.client_update(client)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
Client client = new Client();
client.Name = "My Client";
client.Description = "This is My Client.";
await api.CreateClient(client);
Sample Response
{
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "My Updated Client",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1510911877097,
"defaultMaxAge": 0,
"description": "This is My Updated Client.",
"developer": "john",
"idTokenSignAlg": "RS256",
"modifiedAt": 1510913912201,
"number": 1344,
"serviceNumber": 1043,
"subjectType": "PUBLIC",
"tokenAuthMethod": "CLIENT_SECRET_BASIC"
}
Update an existing client.
Request
POST /api/client/update
PUT /api/client/update
Content-Type
application/json
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
A JSON which represents the client to be updated. The detailed format is described in Client.
Response
Content-Type
application/json
Parameters
A JSON which represents the updated client. The detailed format is described in Client.
/client/delete API
Sample Request
curl -v -X DELETE https://api.authlete.com/api/client/delete/57297408867 \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// The ID of the client to be deleted.
long clientId = 57297408867;
api.deleteClient(clientId);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
# The ID of the client to be deleted.
client_id = 57297408867
api.client_delete(client_id)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// The ID of the client to be deleted.
long clientId = 57297408867;
await api.DeleteClient(clientId);
Sample Response
Delete a client.
Request
DELETE /api/client/delete/{clientId}
Content-Type
application/json
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
The ID of the client to be deleted. |
Response
Content-Type
application/json
Parameters
A JSON which represents the deleted client. The detailed format is described in Client.
/client/secret/refresh API
Sample Request
curl -v https://api.authlete.com/api/client/secret/refresh/57297408867 \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
api.refreshClientSecret(clientId);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
await api.RefreshClientSecret(clientId);
Sample Response
{
"type": "clientSecretRefreshResponse",
"resultCode": "A148001",
"resultMessage": "[A148001] Successfully refreshed the client secret of the client (ID = 57297408867).",
"newClientSecret": "256LJ_49MISH6pP_3WeO8I9wa2LXkZKzqsNGS6XK8srtHYYJyV0jxg-jIaA2Sa0ZA67xA4bpQFKwc94WNUZrWA",
"oldClientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A"
}
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.
Parameters
| Name | Required | Description |
|---|---|---|
clientIdentifier |
YES |
The client ID or the client ID alias of a client. |
Response
Content-Type
application/json
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. |
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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
tring clientSecret = "my_new_client_secret";
api.updateClientSecret(clientId, clientSecret);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
string clientSecret = "my_new_client_secret";
await api.UpdateClientSecret(clientId, clientSecret);
Sample Response
{
"type": "clientSecretUpdateResponse",
"resultCode": "A149001",
"resultMessage": "[A149001] Successfully updated the client secret of the client (ID = 57297408867).",
"newClientSecret": "my_new_client_secret",
"oldClientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A"
}
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.
Parameters
| Name | Required | Description |
|---|---|---|
clientIdentifier |
YES |
The client ID or the client ID alias of a client. |
clientSecret |
YES |
The new value of the client secret.
Valid characters for a client secret are |
Response
Content-Type
application/json
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. |
newClientSecret |
string |
The new client secret. |
oldClientSecret |
string |
The old client secret. |
User Client Authrozation Management
/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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
ClientAuthorizationGetListRequest request = new ClientAuthorizationGetListRequest()
.setSubject("john")
.setStart(0)
.setEnd(3)
;
api.getClientAuthoriztionList(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
ClientAuthorizationGetListRequest request = new ClientAuthorizationGetListRequest();
request.Subject = "john";
request.Start = 0;
request.End = 3;
await api.GetClientAuthorizationList(request);
Sample Response
{
"type": "authorizedClientListResponse",
"clients": [
{
"authTimeRequired": false,
"clientId": 57297408867,
"clientIdAliasEnabled": false,
"clientName": "My Client",
"clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A",
"clientType": "PUBLIC",
"createdAt": 1510911877097,
"defaultMaxAge": 1209600,
"developer": "john",
"extension": {
"requestableScopesEnabled": false
},
"grantTypes": ["AUTHORIZATION_CODE", "IMPLICIT", "PASSWORD", "CLIENT_CREDENTIALS", "REFRESH_TOKEN"],
"idTokenSignAlg": "HS256",
"modifiedAt": 1510911877097,
"number": 1344,
"redirectUris": ["https://api.authlete.com/api/mock/redirection/10167240235"],
"responseTypes": ["NONE", "CODE", "TOKEN", "ID_TOKEN", "CODE_TOKEN", "CODE_ID_TOKEN", "ID_TOKEN_TOKEN", "CODE_ID_TOKEN_TOKEN"],
"serviceNumber": 1034,
"subjectType": "PUBLIC",
"tokenAuthMethod": "CLIENT_SECRET_BASIC"
},
{...},
{...}
],
"end": 3,
"start": 0,
"totalCount": 3,
"subject": "john"
}
Get a list of client applications that an end-user has authorized.
Request
GET /api/client/authorization/get/list/{subject}
GET /api/client/authorization/get/list?subject={subject}
POST /api/client/authorization/get/list
Content-Type
application/x-www-form-urlencoded (POST only)
application/json (POST only)
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
subject |
YES |
Unique user ID. |
start |
NO |
Start index of search results (inclusive). The default value is 0. |
end |
NO |
End index of search results (exclusive). The default value is 5. |
developer |
NO |
Unique Developer ID. The default value is null. |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
start |
i32 |
Start index of search results (inclusive). |
end |
i32 |
End index of search results (exclusive). |
developer |
string |
Unique developer ID. |
totalCount |
i32 |
The 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", "scopes": [{ "name": "my_custom_scope1" }] }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
String subject = "john";
ClientAuthorizationUpdateRequest request = new ClientAuthorizationUpdateRequest().setSubject(subject);
ClientAuthorizationUpdateResponse = api.updateClientAuthoriztion(clientId, request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
ClientAuthorizationUpdateRequest request = new ClientAuthorizationUpdateRequest();
request.Subject = "john";
await api.UpdateClientAuthoriztion(clientId, request);
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.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
The ID of the target client. |
subject |
YES |
Unique user ID. |
scopes |
NO |
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
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. |
/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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
String subject = "john";
api.deleteClientAuthoriztion(clientId, subject);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
String subject = "john";
await api.DeleteClientAuthorization(clientId, subject);
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}?subject={subject}
POST /api/client/authorization/delete/{clientId}
Content-Type
application/x-www-form-urlencoded (POST only)
application/json (POST only)
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
The ID of the target client. |
subject |
YES |
Unique user ID. |
Response
Content-Type
application/json
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. |
Introspection
/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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// An access token to introspect.
String token = "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI";
IntrospectionRequest request = new IntrospectionRequest().setToken(token);
api.introspection(request);
require 'authlete'
api = Authlete::Api.new(
host: 'https://api.authlete.com',
service_api_key: 10167240235,
service_api_secret: 'LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
)
# An access token to introspect.
token = 'VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI'
api.introspection(token)
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// An access token to introspect.
string token = "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI";
IntrospectionRequest request = new IntrospectionRequest();
request.Token = token;
await api.Introspection(request);
Sample Response
{
"type": "introspectionResponse",
"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.
Parameters
| Name | Required | Description |
|---|---|---|
token |
YES |
An access token to introspect. |
scopes |
NO |
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
If this parameter is a non-empty array and if it contains
a scope which is not covered by the access token,
|
subject |
NO |
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 |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
clientId |
i64 |
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 |
i64 |
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 |
|
usable |
boolean |
|
sufficient |
boolean |
|
refreshable |
boolean |
|
responseContent |
string |
The content that the service implementation can
use as the value of |
properties |
Property array |
Extra properties associated with the access token. See Extra Properties for details. |
Description
This API is supposed to be called from within the implementations of protected resource endpoints of the service 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
service implementation should check first because it denotes the next
action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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, ifaccessTokenTypeconfiguration parameter of the service isBearer), the value ofresponseContentcan be used as the value ofWWW-Authenticateheader.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
actionisBAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the service implementation to Authlete does not containtokenrequest parameter).The parameter
responseContentcontains 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, ifaccessTokenTypeconfiguration parameter of the service isBearer), the value ofresponseContentcan be used as the value ofWWW-Authenticateheader.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
actionisUNAUTHORIZED, it means that the access token does not exist or has expired.The parameter
responseContentcontains 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, ifaccessTokenTypeconfiguration parameter of the service isBearer), the value ofresponseContentcan be used as the value ofWWW-Authenticateheader.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
actionisFORBIDDEN, 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
responseContentcontains 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, ifaccessTokenTypeconfiguration parameter of the service isBearer), the value ofresponseContentcan be used as the value ofWWW-Authenticateheader.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
actionisOK, 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
actionisOK, the value ofresponseContentis"Bearer error=\"invalid_request\"". This is the simplest string which can be used as the value ofWWW-Authenticateheader 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 is 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract request parameters which comply with the introspection request defined
// in "2.1. Introspection Request" in RFC 7662.
String parameters = extractRequestParameters();
StandardIntrospectionRequest request = new StandardIntrospectionRequest().setParameters(parameters);
api.standardIntrospection(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract request parameters which comply with the introspection request defined
// in "2.1. Introspection Request" in RFC 7662.
string parameters = ExtractRequestParameters();
StandardIntrospectionRequest request = new StandardIntrospectionRequest();
request.Parameters = parameters;
await api.StandardIntrospection(request);
Sample Response
{
"type": "standardIntrospectionResponse",
"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\",\"aud\":[\"57297408867\"],\"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.
Parameters
| Name | Required | Description |
|---|---|---|
parameters |
YES |
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.
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
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
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 service implementation should
retrieve the value of action from the response and take the
following steps according to the value.
INTERNAL_SERVER_ERROR-
When the value of
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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 service 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
actionisBAD_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
responseContentcontains 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 service implementation generates and returns to the client application.
HTTP/1.1 400 Bad Request Content-Type: application/json {responseContent} OK-
When the value of
actionisOK, 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
responseContentcontains 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 service 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
/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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// Extract request parameters that the OAuth 2.0 token revocation endpoint of
// this OAuth 2.0 serever implementation received from the client application.
String parameters = extractRequestParameters();
RevocationRequest request = new RevocationRequest().setParameters(parameters);
api.revocation(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// Extract request parameters that the OAuth 2.0 token revocation endpoint of
// this OAuth 2.0 serever implementation received from the client application.
string parameters = ExtractRequestParameters();
RevocationRequest request = new RevocationRequest();
request.Parameters = parameters;
await api.Revocation(request);
Sample Response
{
"type": "revocationResponse",
"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.
Parameters
| Name | Required | Description |
|---|---|---|
parameters |
YES |
OAuth 2.0 token revocation request parameters which are the request parameters that the OAuth 2.0 token revocation endpoint (RFC 7009) of the service implementation received from the client application.
The value of |
clientId |
NO |
The client ID extracted from
If the token revocation endpoint of the service implementation
supports Basic Authentication
as a means of client authentication, and the request from the
client application contains its client ID in |
clientSecret |
NO |
The client secret extracted from
If the token revocation endpoint of the service implementation
supports Basic Authentication
as a means of client authentication, and the request from the
client application contains its client secret in |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service 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 service 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
service implementation should check first because it denotes the next
action that the service implementation should take. According to the
value of action, the service implementation must take the
steps described below.
INVALID_CLIENT-
When the value of
actionisINVALID_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 aboutinvalid_clientshown 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
Authorizationrequest header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include theWWW-Authenticateresponse header field matching the authentication scheme used by the client.
In either case, the value of
responseContentcontains 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentcontains 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
actionisBAD_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
responseContentcontains 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} OK-
When the value of
actionisOK, 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
callbackrequest parameter and its value is not empty, the content type should beapplication/javascriptand the content should be a JavaScript snippet for JSONP.The parameter
responseContentcontains a JavaScript snippet if the original request from the client application containscallbackrequest parameter and its value is not empty. Otherwise, the value ofresponseContentis null.HTTP/1.1 200 OK Content-Type: application/javascript Cache-Control: no-store Pragma: no-cache {responseContent}
Userinfo
/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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// An access token to get user information.
String token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI";
UserInfoRequest request = new UserInfoRequest().setToken(token);
api.userinfo(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// An access token to get user information.
string token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI";
UserInfoRequest request = new UserInfoRequest();
request.Token = token;
await api.UserInfo(request);
Sample Response
{
"type": "userInfoResponse",
"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.
Parameters
| Name | Required | Description |
|---|---|---|
token |
YES |
An access token to get user information. |
Response
Content-Type
application/x-www-form-urlencoded
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
claims |
string array |
The list of claims that the client application requests to be embedded in the ID token. |
clientId |
i64 |
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 service implementation can use
as the value of |
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. |
Description
This API is supposed to be called from within the implementation of the UserInfo Endpoint of the service 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 service implementation should check first because it denotes
the next action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentreturns 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisBAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the service implementation to Authlete does not containtokenparameter).The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisUNAUTHORIZED, it means that the access token does not exist, has expired, or is not associated with any subject (= any user account).The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisFORBIDDEN, it means that the access token does not include theopenidscope.The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisOK, 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 theopenidscope, 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
subjectparameter in the response from this API and the names of data, i.e., the claims names are contained in theclaimsparameter in the response. For example, if thesubjectparameter isjoe123and theclaimsparameter 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/issueAPI 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-cacheAlso, 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" }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
// The access token that has been passed to the service's UserInfo Endpoint by the client application.
String token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI"
UserInfoIssueRequest request = new UserInfoIssueRequest().setToken(token);
api.userinfoIssue(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
// The access token that has been passed to the service's UserInfo Endpoint by the client application.
string token = "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI";
UserInfoIssueRequest request = new UserInfoIssueRequest();
request.Token = token;
await api.UserInfoIssue(request);
Sample Response
{
"type": "userInfoIssueResponse",
"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.
Parameters
| Name | Required | Description |
|---|---|---|
token |
YES |
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 |
NO |
Claims in JSON format. As for the format, see "OpenID Connect Core 1.0, 5.1. Standard Claims". |
sub |
NO |
The value of the |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
responseContent |
string |
The content that the service implementation can use
as the value of |
Description
This API is supposed to be called from within the implementation of
the UserInfo Endpoint
of the service 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 service implementation should check first because it denotes
the next action that the service 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
actionisINTERNAL_SERVER_ERROR, it means that the request from the service 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
responseContentreturns 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisBAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the service implementation to Authlete does not containtokenparameter).The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisUNAUTHORIZED, it means that the access token does not exist, has expired, or is not associated with any subject (= any user account).The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisFORBIDDEN, it means that the access token does not include theopenidscope.The parameter
responseContentcontains 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 ofresponseContentas the value ofWWW-Authenticateheader.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
actionisJSON, 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/jsonand the response body must be an ID token in JSON format.The parameter
responseContentcontains the ID token in JSON format whenactionisJSON, 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
actionisJWT, 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/jwtand the response body must be an ID token in JWT format.The parameter
responseContentcontains the ID token in JWT format whenactionisJWT, 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
/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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
api.getServiceJwks();
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
await api.GetServiceJwks();
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 /service/jwks/get
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
includePrivateKeys |
NO |
This boolean value indicates whether the response should include
the private keys associated with the service or not.
If |
pretty |
NO |
This boolean value indicates whether the JSON in the response
should be formatted or not.
If |
Response
Content-Type
application/json
Parameters
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
/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"
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
api.getServiceConfiguration();
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
await api.GetServiceConfiguration();
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",
"code",
"token",
"id_token",
"code token",
"code id_token",
"id_token token",
"code id_token token"
],
"response_modes_supported": [
"query",
"fragment",
"form_post"
],
"grant_types_supported": [
"authorization_code",
"implicit",
"password",
"client_credentials",
"refresh_token"
],
"subject_types_supported": [
"public"
],
"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"
],
"token_endpoint_auth_methods_supported": [
"none",
"client_secret_basic",
"client_secret_post"
],
"display_values_supported": [
"page",
"popup",
"touch",
"wap"
],
"claim_types_supported": [
"normal"
],
"claims_supported": [
"zoneinfo",
"sub",
"phone_number",
"nickname",
"website",
"middle_name",
"email_verified",
"locale",
"phone_number_verified",
"preferred_username",
"given_name",
"picture",
"updated_at",
"address",
"email",
"name",
"birthdate",
"gender",
"family_name",
"profile"
],
"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",
"code_challenge_methods_supported": [
"plain",
"S256"
]
}
This API gathers configuration information of a service.
Request
GET /service/configuration
Content-Type
application/json
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
pretty |
NO |
This boolean value indicates whether the JSON in the response
should be formatted or not.
If |
Response
Content-Type
application/json
Parameters
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.
Token Operations
/auth/token/get/list API
Sample Request
curl -v https://api.authlete.com/api/auth/token/get/list/john?start=0\&end=3 \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
# This API is not supported yet.
# This API is not supported yet.
# This API is not supported yet.
Sample Response
{
"accessTokens": [
{
"accessTokenExpiresAt": 1527583747000,
"accessTokenHash": "kjjduowWXMPiHt1AjxbgkqWANOsVWQfKYCyFO76q1MU",
"clientId": 11867130158,
"createdAt": 1527497347000,
"grantType": "AUTHORIZATION_CODE",
"lastRefreshedAt": 0,
"refreshTokenExpiresAt": 1528361347000,
"refreshTokenHash": "hCkIkuS6py0drpe5XOybw0MxkgsYNOk2q3dtilLiI64",
"scopes": ["openid"],
"subject": "john"
},
{...},
{...}
],
"end": 3,
"start": 0,
"totalCount": 15
}
Get a list of client applications that an end-user has authorized.
Request
GET /auth/token/get/list
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
clientIdentifier |
NO |
Client Identifier (client ID or client ID alias). |
subject |
NO |
Unique user ID. |
start |
NO |
Start index of search results (inclusive). The default value is 0. |
end |
NO |
End index of search results (exclusive). The default value is 5. |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
start |
i32 |
Start index of search results (inclusive). |
end |
i32 |
End index of search results (exclusive). |
totalCount |
i32 |
The total number of access tokens that meet the conditions. |
accessTokens |
AccessToken array |
An array of access tokens. |
/auth/token/create API
Sample Request
curl -v -X POST https://api.authlete.com/api/auth/token/create \
-H 'Content-Type:application/json' \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
-d '{ "grantType": "AUTHORIZATION_CODE", "clientId": 57297408867, "subject": "john", "scopes": [ "openid" ] }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
TokenCreateRequest request = new TokenCreateRequest()
.setGrantType(GrantType.AUTHORIZATION_CODE)
.setClientId(57297408867)
.setSubject("john")
.setScopes({ "openid" });
api.tokenCreate(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
TokenCreateRequest request = new TokenCreateRequest();
request.GrantType = GrantType.AUTHORIZATION_CODE;
request.ClientId = 57297408867;
request.Subject = "john";
request.Scopes = { "openid" };
await api.TokenCreate(request);
Sample Response
{
"type": "tokenCreateResponse",
"resultCode": "A109001",
"resultMessage": "[A109001] An access token was created successfully: authorization_code, client = 57297408867",
"accessToken": "ILuFMMKP-oTY9hFVSUKo9NKiyOwyrcSvxNicxSQ9maA",
"action": "OK",
"clientId": 57297408867,
"expiresAt": 1511246182637,
"expiresIn": 86400,
"grantType": "AUTHORIZATION_CODE",
"refreshToken": "zRMu25sREDJS9qRZUr3j9Qb_hrUZxSUQRkahi0giyyZ",
"subject": "john",
"tokenType": "Bearer"
}
Create an access token.
Request
GET /api/auth/token/create
POST /api/auth/token/create
Content-Type
application/x-www-form-urlencoded (POST only)
application/json (POST only)
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
grantType |
YES |
The grant type for a newly created access token.
One of the following.
When See the description of grant types for details about the values above. |
clientId |
YES |
The ID of the client application which will be associated with a newly created access token. |
subject |
CONDITIONALLY REQUIRED |
The subject (= unique identifier) of the user
who will be associated with a newly created access
token. This parameter is required unless the grant
type is |
scopes |
NO |
The scopes which will be associated with a newly created access token. Scopes that are not supported by the service cannot be specified and requesting them will cause an error. |
accessTokenDuration |
NO |
The duration of a newly created access token in seconds. If the value is 0, the duration is determined according to the settings of the service. |
refreshTokenDuration |
NO |
The duration of a newly created refresh token in seconds. If the value is 0, the duration is determined according to the settings of the service.
A refresh token is not created (1) if the service does
not support |
properties |
NO |
Extra properties to associate with a newly created access
token. Note that |
clientIdAliasUsed |
NO |
A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created.
This has an effect only on the value of the
Note that if a client ID alias is not assigned to the client when Authlete's
|
accessToken |
NO |
The value of the new access token.
The
Note that if the hash value of the specified access token already
exists in Authlete's database, the access token cannot be inserted
and the |
refreshToken |
NO |
The value of the new refresh token.
The
Note that if the hash value of the specified refresh token already
exists in Authlete's database, the refresh token cannot be inserted
and the |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
accessToken |
string |
The newly issued access token. |
clientId |
i64 |
The ID of the client application which is associated with the access token. |
expiresAt |
i64 |
The time at which the access token expires. |
expiresIn |
i64 |
The duration of the newly issued access token in seconds. |
grantType |
GrantType |
The grant type for the newly issued access token. |
properties |
Property array |
The properties associated with the access token. See Extra Properties for details. |
refreshToken |
string |
The newly issued refresh token. |
scopes |
string array |
Scopes which are associated with the access token. |
subject |
string |
The subject (= unique identifier) of the user associated with the newly issued access token. |
tokenType |
string |
The token type of the access token. |
Description
This API is supposed to be called to create an arbitrary access token in a special way that is different from standard grant flows.
The response from /auth/token/create API has various
parameters. Among them, it is action parameter that
the service implementation should check first because it denotes
the next action that the service 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
actionparameter isINTERNAL_SERVER_ERROR, it means that an error occurred on Authlete side. BAD_REQUEST-
When the value of
actionparameter isBAD_REQUEST, it means that the request from the caller was wrong. For example, this happens when thegrantTyperequest parameter is not specified. FORBIDDEN-
When the value of
actionisFORBIDDEN, it means that the request from the caller is not allowed. For example, this happens when the client application identified by theclientIdrequest parameter does not belong to the service identified by the API key used for the API call. OK-
When the value of
actionparameter isOK, it means that everything was processed successfully and an access token and optionally a refresh token were issued.
/auth/token/update API
Sample Request
curl -v -X POST https://api.authlete.com/api/auth/token/update \
-H 'Content-Type:application/json' \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE' \
-d '{ "accessToken": "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs", "scopes": ["email", "openid"] }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
TokenUpdateRequest request = new TokenUpdateRequest()
.setAccessToken("JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs")
.setScopes({ "email", "openid" });
api.tokenUpdate(request);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
TokenUpdateRequest request = new TokenUpdateRequest();
request.AccessToken = "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs";
request.Scopes = { "email", "openid" };
await api.TokenUpdate(request);
Sample Response
{
"type": "tokenUpdateResponse",
"resultCode": "A135001",
"resultMessage": "[A135001] Updated the access token successfully.",
"accessToken": "JDGiiM9PuWT63FIwGjG9eYlGi-aZMq6CQ2IB475JUxs",
"accessTokenExpiresAt": 1511847449000,
"action": "OK",
"scopes": ["email", "openid"]
}
Update an existing access token.
Request
POST /api/auth/token/update
PUT /api/auth/token/update
Content-Type
application/x-www-form-urlencoded
application/json
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
accessToken |
YES |
An existing access token. |
accessTokenExpiresAt |
NO |
A new date at which the access token will expire in milliseconds
since the Unix epoch (1970-01-01). If the |
scopes |
NO |
A new set of scopes assigned to the access token. Scopes that are
not supported by the service and those that the client application
associated with the access token is not allowed to request are
ignored on the server side. If the |
properties |
NO |
A new set of properties assigned to the access token. If the |
Response
Content-Type
application/json
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. |
action |
string |
The next action that the service implementation should take. One of the following. Details are described in the description.
|
accessToken |
string |
The access token which has been specified by the request. |
accessTokenExpiresAt |
i64 |
The date at which the access token will expire. |
properties |
Property array |
The properties associated with the access token. See Extra Properties for details. |
scopes |
string array |
The scopes associated with the access token. |
Description
This API is supposed to be called to update an existing access token.
The response from /auth/token/update API has various
parameters. Among them, it is action parameter that
the service implementation should check first because it denotes
the next action that the service 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
actionparameter isINTERNAL_SERVER_ERROR, it means that an error occurred on Authlete side. BAD_REQUEST-
When the value of
actionparameter isBAD_REQUEST, it means that the request from the caller was wrong. For example, this happens when theaccessTokenrequest parameter is not specified. FORBIDDEN-
When the value of
actionisFORBIDDEN, it means that the request from the caller is not allowed. For example, this happens when the access token identified by theaccessTokenrequest parameter does not belong to the service identified by the API key used for the API call. NOT_FOUND-
When the value of
actionparameter isNOT_FOUND, it means that the specified access token does not exist. OK-
When the value of
actionparameter isOK, it means that the access token was updated successfully.
Requestable Scopes Per Client
/client/extension/requestable_scopes/get API
Sample Request
curl -v https://api.authlete.com/api/client/extension/requestable_scopes/get/57297408867?pretty=true \
-u '10167240235:LFpGEwpyHKNYMeMHg-H339X8gXdVlix-GoCHQAjAMaE'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
api.getRequestableScopes(clientId);
# This API is not supported yet.
// 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.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
A client ID. |
pretty |
NO |
This boolean value indicates whether the JSON in the response
should be formatted or not.
If |
Response
Content-Type
application/json
Parameters
| 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.
|
Description
What is indicated by the value of the requestableScopes
parameter in the response from this API is as follows.
null-
When the value of
requestableScopesparameter isnull, 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
requestableScopesparameter 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
requestableScopesparameter 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" ] }'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
String[] scopes = { "email", "openid" };
api.setRequestableScopes(clientId, scope);
# This API is not supported yet.
// 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.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
A client ID. |
requestableScopes |
NO |
A new set of scopes that the client application is allowed to request. This must be one of the following.
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
|
pretty |
NO |
This boolean value indicates whether the JSON in the response
should be formatted or not.
If |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
requestableScopes |
string array |
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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
api.deleteRequestableScopes(clientId);
# This API is not supported yet.
// This API is not supported yet.
Sample Response
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.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
A client ID. |
Response
Description
The set of socpes that the client application is allowed to request was deleted successfully or did not exist.
Granted Scopes
In Dedicated Server Plan, Authlete Server remembers who (end-user) has granted what permissions (scopes) to which client application. The records are kept even after all access tokens are expired unless you delete the records explicitly or unless the client application or the service is deleted. Using the API, you can build an authorization page where an end-user is not asked repeatedly to give permissions to a client application when the end-user has already given the permissions to the client application in the past.
/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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
String subject = "john";
api.getGrantedScopes(clientId, subject);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
string subject = "john";
await api.GetGrantedScopes(clientId, subject);
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}&subject={subject}
POST /api/client/granted_scopes/get/{clientId}
Content-Type
application/x-www-form-urlencoded (POST only)
application/json (POST only)
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
Client ID. |
subject |
YES |
Unique user ID. |
Response
Content-Type
application/json
Parameters
| Name | Type | Description |
|---|---|---|
serviceApiKey |
string |
Service API key. |
clientId |
string |
Client ID. |
subject |
string |
Unique user ID. |
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'
AuthleteApi api = AuthleteApiFactory.getDefaultApi();
long clientId = 57297408867;
String subject = "john";
api.deleteGrantedScopes(clientId, subject);
# This API is not supported yet.
IAuthleteConfiguration conf = new AuthletePropertiesConfiguration();
IAuthleteApi api = new AuthleteApi(conf);
long clientId = 57297408867;
string subject = "john";
await api.DeleteGrantedScopes(clientId, subject);
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
DELETE /api/client/granted_scopes/delete/{clientId}/{subject}
DELETE /api/client/granted_scopes/delete/{clientId}&subject={subject}
POST /api/client/granted_scopes/delete/{clientId}
Content-Type
application/x-www-form-urlencoded (POST only)
application/json (POST only)
Authorization
Basic Authentication with API key & API secret of a service.
Parameters
| Name | Required | Description |
|---|---|---|
clientId |
YES |
Client ID. |
subject |
YES |
Unique user ID. |
Response
Content-Type
application/json
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. |
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.
Result Codes
A000101
Sorry, an unexpected error occurred on Authlete's side.
A001101
Sorry, an unexpected error occurred on Authlete's side.
A001201
Check if the API's URL you specified starts with https://, not http://.
A001202
This API requires Basic Authentication. Include Authorization HTTP header in your API call.
A001203
Check if the format of the value of Authorization HTTP header in your API call complies with the specification of Basic Authentication.
A001212
Check if the client ID you specified is correct.
A001213
A001214
The client application has been logically deleted, so it cannot be used.
A001215
The client application is currently locked for some reasons, so it cannot be used.
A001216
A001217
Consult our support team if you want to use this API.
A001218
Check if the client identifier you specified is correct. If you used a client alias, check if the feature of client ID alias is enabled both in the client configuration and in the service configuration.
A001219
A001220
A001221
A001222
A002101
Sorry, an error occurred on the server side in getting the information about the service owner from the database.
A002201
Check if the pair of API key and API secret you specified is correct.
A002202
The service owner has been logically deleted, so services and client applications that belong to the service owner cannot be used.
A002203
The service owner is currently locked for some reasons, so services and client applications that belong to the service owner cannot be used.
A002204
A002205
Check if the pair of API key and API secret you specified is correct.
A003101
Sorry, there is an inconsistency on Authlete's side.
A003102
Sorry, there is an inconsistency on Authlete's side.
A003103
Sorry, an error occurred on the server side in getting the information about the service from the database.
A003104
Sorry, an error occurred on the server side in getting the information about the service owner from the database.
A003201
Check if the pair of API key and API secret you specified is correct.
A003202
The service has been logically deleted, so it cannot be used.
A003203
The service is currently locked for some reasons, so it cannot be used.
A003204
Check if the API secret you specified is correct.
A003205
The service owner of the service has been logically deleted, so the service cannot be used.
A003206
The service owner of the service is currently locked for some reasons, so the service cannot be used.
A004001
The call of /api/auth/authorization API succeeded.
A004201
Include the parameters request parameter when you call Authlete's /api/auth/authorization API.
A004202
Check if the value of the parameters request parameter given to Authlete's /api/auth/authorization API complies with x-www-form-urlencoded.
A004301
A004302
A004303
A005101
A005102
A005103
A005104
A005105
A005106
A005107
A005108
A005109
A005110
A005111
A005112
A005113
A005114
A005201
The client application should not encrypt the request object, or the service should register its JWK Set into Authlete.
A005202
The request object pointed to by the URL should not be encrypted (the developer of the client application should fix it), or the service should register its JWK Set into Authlete.
A005203
The client application should not encrypt the request object, or the service should register its JWK Set into Authlete.
A005204
The request object pointed to by the URL should not be encrypted (the developer of the client application should fix it), or the service should register its JWK Set into Authlete.
A005301
The client application should be fixed to construct a valid request object.
A005302
The client application should be fixed to construct a valid request object.
A005303
The developer of the client application should fix the request object pointed to by the URL (request_uri).
A005304
The developer of the client application should fix the request object pointed to by the URL (request_uri).
A005305
The client application should be fixed to construct a valid request object.
A005306
The developer of the client application should fix the request object pointed to by the URL (request_uri).
A005307
The client application should be fixed to include the alg parameter.
A005308
The client application should be fixed to include the alg parameter.
A005309
The developer of the client application should fix the request object pointed to by the URL (request_uri) to include the alg parameter.
A005310
The developer of the client application should fix the request object pointed to by the URL (request_uri) to include the alg parameter.
A005311
Authlete tried to fetch the JWK Set of the client application from the registered URL but in vain. The developer of the client application should check if the URL is valid and it returns a valid JWK Set.
A005312
The client application should be fixed to use the registered algorithm for signing the request object, or the developer of the client application should change the registered value of the requestSignAlg property.
A005313
The client application should be fixed to use the registered algorithm for signing the request object, or the developer of the client application should change the registered value of the requestSignAlg property.
A005314
The request object pointed to by the URL (request_uri) should be signed with the registered algorithm, or the developer of the client application should change the registered value of the requestSignAlg property.
A005315
The client application should be signed with the registered algorithm, or the developer of the client application should change the registered value of the requestSignAlg property.
A005316
The client application should not use the algorithm for signing the request object. The developer of the client application should either change the client type to confidential (= change the registered value of the clientType property to CONFIDENTIAL) or change the registered algorithm to one of asymmetric algorithms (= change the registered value of the requestSignAlg property) and fix the application code to use the asymmetric algorithm.
A005317
The client application should not use the algorithm for signing the request object. The developer of the client application should either change the client type to confidential (= change the registered value of the clientType property to CONFIDENTIAL) or change the registered algorithm to one of asymmetric algorithms (= change the registered value of the requestSignAlg property) and fix the application code to use the asymmetric algorithm.
A005318
The algorithm should not be used to sign the request object pointed to by the URL (request_uri). The developer of the client application should either change the client type to confidential (= change the registered value of the clientType property to CONFIDENTIAL) or change the registered algorithm to one of asymmetric algorithms (= change the registered value of the requestSignAlg property) and sign the request object with the asymmetric algorithm.
A005319
The algorithm should not be used to sign the request object pointed to by the URL (request_uri). The developer of the client application should either change the client type to confidential (= change the registered value of the clientType property to CONFIDENTIAL) or change the registered algorithm to one of asymmetric algorithms (= change the registered value of the requestSignAlg property) and sign the request object with the asymmetric algorithm.
A005320
The client application should be fixed to use one of the supported algorithms for sigining the request object.
A005321
The client application should be fixed to use one of the supported algorithms for sigining the request object.
A005322
The request object pointed to by the URL (request_uri) should be signed with one of the supported algorithms.
A005323
The client application should be fixed to use one of the supported algorithms for sigining the request object.
A005324
The client application should be fixed to sign the request object correctly.
A005325
The client application should be fixed to sign the request object correctly.
A005326
The request object pointed to by the URL (request_uri) should be signed correctly.
A005327
The request object pointed to by the URL (request_uri) should be signed correctly.
A005328
The client application should be fixed to use the correct private or shared key for signing the request object.
A005329
The client application should be fixed to use the correct private or shared key for signing the request object.
A005330
The request object pointed to by the URL (request_uri) should be signed with the correct private or shared key.
A005331
The request object pointed to by the URL (request_uri) should be signed with the correct private or shared key.
A005332
The developer of the client application should register the JWK Set (containing the paired public key) of the client application into the service (as the value of the jwks property), or make it accessible somewhere and register its URL into the service (as the value of the jwksUri property).
A005333
The developer of the client application should register the JWK Set (containing the paired public key) of the client application into the service (as the value of the jwks property), or make it accessible somewhere and register its URL into the service (as the value of the jwksUri property).
A005334
The developer of the client application should register the JWK Set (containing the paired public key) of the client application into the service (as the value of the jwks property), or make it accessible somewhere and register its URL into the service (as the value of the jwksUri property).
A005335
The developer of the client application should register the JWK Set (containing the paired public key) of the client application into the service (as the value of the jwks property), or make it accessible somewhere and register its URL into the service (as the value of the jwksUri property).
A005336
The client application should be fixed to sign the request object with the registered algorithm (the value of the requestSignAlg property), or the developer of the client application should change the value of the registered algorithm to none or null.
A005337
The client application should be fixed to sign the request object with the registered algorithm (the value of the requestSignAlg property), or the developer of the client application should change the value of the registered algorithm to none or null.
A005338
The request object pointed to by the URL (request_uri) should be signed with the registered algorithm (the value of the requestSignAlg property), or the developer of the client application should change the value of the registered algorithm to none or null.
A005339
The request object pointed to by the URL (request_uri) should be signed with the registered algorithm (the value of the requestSignAlg property), or the developer of the client application should change the value of the registered algorithm to none or null.
A005340
The developer of the client application should check if the JWK Set pointed to by the registered URL (the value of jwksUri property) contains the public key for the combination of the algorithm and the key ID.
A005341
The developer of the client application should check if the JWK Set pointed to by the registered URL (the value of jwksUri property) contains the public key for the combination of the algorithm and the key ID.
A005342
The developer of the client application should check if the JWK Set pointed to by the registered URL (the value of jwksUri property) contains the public key for the combination of the algorithm and the key ID.
A005343
The developer of the client application should check if the JWK Set pointed to by the registered URL (the value of jwksUri property) contains the public key for the combination of the algorithm and the key ID.
A005344
Either or both the client application and the JWK Set pointed to by the registered URL (the value of jwksUri property) should be fixed so that Authlete can identify the public key to use for signature verification. For example, unique key IDs should be assigned to the candidate public keys and the client application should specify one of the key IDs in the request object as the value of kid.
A005345
Either or both the client application and the JWK Set pointed to by the registered URL (the value of jwksUri property) should be fixed so that Authlete can identify the public key to use for signature verification. For example, unique key IDs should be assigned to the candidate public keys and the client application should specify one of the key IDs in the request object as the value of kid.
A005346
Either or both the request object pointed to by the URL (request_uri) and the JWK Set pointed to by the registered URL (the value of jwksUri property) should be fixed so that Authlete can identify the public key to use for signature verification. For example, unique key IDs should be assigned to the candidate public keys and the request object should include one of the key IDs as the value of kid.
A005347
Either or both the request object pointed to by the URL (request_uri) and the JWK Set pointed to by the registered URL (the value of jwksUri property) should be fixed so that Authlete can identify the public key to use for signature verification. For example, unique key IDs should be assigned to the candidate public keys and the request object should include one of the key IDs as the value of kid.
A005348
Check if the JWK Set is formatted correctly.
A005349
This may happen while the configuration of the client application is temporarily inconsistent. Try later again.
A005350
Probably, the client application was deleted while the API call was being processed.
A005351
The developer of the client application should register the JWK Set of the client application.
A005352
The developer of the client application should update the JWK Set (= the value of jwks property) to include the public key.
A005353
The developer of the client application should update the JWK Set (= the value of jwks property) to include the public key.
A005354
The developer of the client application should update the JWK Set (= the value of jwks property) to include the public key.
A005355
The developer of the client application should update the JWK Set (= the value of jwks property) to include the public key.
A005356
Either or both the client application and the registered JWK Set (the value of jwks property) should be fixed so that Authlete can identify the public key to use for signature verification. For example, unique key IDs should be assigned to the candidate public keys and the client application should specify one of the key IDs in the request object as the value of kid.