com.authlete.common.api

Interface AuthleteApi

public interface AuthleteApi

Authlete API.

Author:

Takahiko Kawasaki

Method Summary

Modifier and Type	Method and Description
AuthorizationResponse	authorization(AuthorizationRequest request) Call Authlete's /auth/authorization API.
AuthorizationFailResponse	authorizationFail(AuthorizationFailRequest request) Call Authlete's /auth/authorization/fail API.
AuthorizationIssueResponse	authorizationIssue(AuthorizationIssueRequest request) Call Authlete's /auth/authorization/issue API.
Client	createClient(Client client) Create a client (= call Authlete's /client/create API).
Service	createServie(Service service) Create a service (= call Authlete's /service/create API).
void	deleteClient(long clientId) Delete a client (= call Authlete's /client/delete/{clientId} API).
void	deleteClientAuthorization(long clientId, String subject) Delete all existing access tokens issued to the client application by the end-user.
void	deleteGrantedScopes(long clientId, String subject) Delete DB records about the set of scopes that a user has granted to a client application (call Authlete's /client/granted_scopes/delete/{clientId} API).
void	deleteRequestableScopes(long clientId) Clear the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/delete/{clientId} API).
void	deleteService(long apiKey) Delete a service (= call Authlete's /service/delete/{apiKey} API).
Client	getClient(long clientId) Get a client (= call Authlete's /client/get/{clientId} API).
AuthorizedClientListResponse	getClientAuthorizationList(ClientAuthorizationGetListRequest request) Get a list of client applications authorized by the end-user.
ClientListResponse	getClientList() Get the list of client applications that belong to the service (= call Authlete's /client/get/list API).
ClientListResponse	getClientList(int start, int end) Get the list of client applications that belong to the service (= call Authlete's /client/get/list API with start and end parameters).
ClientListResponse	getClientList(String developer) Get the list of client applications that belong to the developer (= call Authlete's /client/get/list API with developer parameter).
ClientListResponse	getClientList(String developer, int start, int end) Get the list of client applications (= call Authlete's /client/get/list API with developer, start and end parameters).
GrantedScopesGetResponse	getGrantedScopes(long clientId, String subject) Get the set of scopes that a user has granted to a client application (call Authlete's /client/granted_scopes/get/{clientId} API).
String[]	getRequestableScopes(long clientId) Get the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/get/{clientId} API).
Service	getService(long apiKey) Get a service (= call Authlete's /service/get/{apiKey} API).
String	getServiceConfiguration() Get the configuration of the service in JSON format that complies with OpenID Connect Discovery 1.0.
String	getServiceConfiguration(boolean pretty) Get the configuration of the service in JSON format that complies with OpenID Connect Discovery 1.0.
String	getServiceJwks() Get the JWK Set of a service.
String	getServiceJwks(boolean pretty, boolean includePrivateKeys) Get the JWK Set of a service.
ServiceListResponse	getServiceList() Get the list of services that belong to the service owner (= call Authlete's /service/get/list API).
ServiceListResponse	getServiceList(int start, int end) Get the list of services that belong to the service owner (= call Authlete's /service/get/list API with start and end parameters).
Settings	getSettings() Get the reference to the settings of this AuthleteApi implementation.
IntrospectionResponse	introspection(IntrospectionRequest request) Call Authlete's /auth/introspection API.
RevocationResponse	revocation(RevocationRequest request) Call Authlete's /auth/revocation API.
String[]	setRequestableScopes(long clientId, String[] scopes) Set the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/update/{clientId} API).
StandardIntrospectionResponse	standardIntrospection(StandardIntrospectionRequest request) Call Authlete's /auth/introspection/standard API.
TokenResponse	token(TokenRequest request) Call Authlete's /auth/token API.
TokenCreateResponse	tokenCreate(TokenCreateRequest request) Call Authlete's /auth/token/create API.
TokenFailResponse	tokenFail(TokenFailRequest request) Call Authlete's /auth/token/fail API.
TokenIssueResponse	tokenIssue(TokenIssueRequest request) Call Authlete's /auth/token/issue API.
TokenUpdateResponse	tokenUpdate(TokenUpdateRequest request) Call Authlete's /auth/token/update API.
Client	updateClient(Client client) Update a client (= call Authlete's /client/update/{clientId} API).
void	updateClientAuthorization(long clientId, ClientAuthorizationUpdateRequest request) Update attributes of all existing access tokens issued to the client application by the end-user.
Service	updateService(Service service) Update a service (= call Authlete's /service/update/{apiKey} API).
UserInfoResponse	userinfo(UserInfoRequest request) Call Authlete's /auth/userinfo API.
UserInfoIssueResponse	userinfoIssue(UserInfoIssueRequest request) Call Authlete's /auth/userinfo/issue API.

Method Detail

authorization

AuthorizationResponse authorization(AuthorizationRequest request)
                             throws AuthleteApiException

Call Authlete's /auth/authorization API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

authorizationFail

AuthorizationFailResponse authorizationFail(AuthorizationFailRequest request)
                                     throws AuthleteApiException

Call Authlete's /auth/authorization/fail API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

authorizationIssue

AuthorizationIssueResponse authorizationIssue(AuthorizationIssueRequest request)
                                       throws AuthleteApiException

Call Authlete's /auth/authorization/issue API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

token

TokenResponse token(TokenRequest request)
             throws AuthleteApiException

Call Authlete's /auth/token API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

tokenCreate

TokenCreateResponse tokenCreate(TokenCreateRequest request)
                         throws AuthleteApiException

Call Authlete's /auth/token/create API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

Since:

1.13

tokenFail

TokenFailResponse tokenFail(TokenFailRequest request)
                     throws AuthleteApiException

Call Authlete's /auth/token/fail API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

tokenIssue

TokenIssueResponse tokenIssue(TokenIssueRequest request)
                       throws AuthleteApiException

Call Authlete's /auth/token/issue API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

tokenUpdate

TokenUpdateResponse tokenUpdate(TokenUpdateRequest request)
                         throws AuthleteApiException

Call Authlete's /auth/token/update API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

Since:

1.34

revocation

RevocationResponse revocation(RevocationRequest request)
                       throws AuthleteApiException

Call Authlete's /auth/revocation API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

Since:

1.16

userinfo

UserInfoResponse userinfo(UserInfoRequest request)
                   throws AuthleteApiException

Call Authlete's /auth/userinfo API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

userinfoIssue

UserInfoIssueResponse userinfoIssue(UserInfoIssueRequest request)
                             throws AuthleteApiException

Call Authlete's /auth/userinfo/issue API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

introspection

IntrospectionResponse introspection(IntrospectionRequest request)
                             throws AuthleteApiException

Call Authlete's /auth/introspection API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

standardIntrospection

StandardIntrospectionResponse standardIntrospection(StandardIntrospectionRequest request)
                                             throws AuthleteApiException

Call Authlete's /auth/introspection/standard API.

Parameters:

request - Request parameters passed to the API.

Returns:

Response from the API.

Throws:

AuthleteApiException

Since:

2.7

createServie

Service createServie(Service service)
              throws AuthleteApiException

Create a service (= call Authlete's /service/create API).

Parameters:

service - Information about a service to create.

Returns:

Information about a newly created service.

Throws:

AuthleteApiException

deleteService

void deleteService(long apiKey)
            throws AuthleteApiException

Delete a service (= call Authlete's /service/delete/{apiKey} API).

Parameters:

apiKey - The API key of the service.

Throws:

AuthleteApiException

getService

Service getService(long apiKey)
            throws AuthleteApiException

Get a service (= call Authlete's /service/get/{apiKey} API).

Parameters:

apiKey - The API key of the service.

Returns:

Information about the service.

Throws:

AuthleteApiException

getServiceList

ServiceListResponse getServiceList()
                            throws AuthleteApiException

Get the list of services that belong to the service owner (= call Authlete's /service/get/list API).

This method uses the default range to limit the result set of the query. Use getServiceList(int, int) to specify the range explicitly.

Returns:

The list of services.

Throws:

AuthleteApiException

getServiceList

ServiceListResponse getServiceList(int start,
                                   int end)
                            throws AuthleteApiException

Get the list of services that belong to the service owner (= call Authlete's /service/get/list API with start and end parameters).

The pair of start and end parameters denotes the range of the result set of the query. For example, if start is 5 and end is 7, the pair makes a range from 5 (inclusive) to 7 (exclusive) and the response will contain (at most) 2 pieces of service information, i.e., information about the 6th and the 7th services (the index starts from 0).

If end - start is equal to or less than 0, getServices() method of the response returns null. But even in such a case, getTotalCount() method returns the total count. In other words, if you want to get just the total count, you can write the code as shown below.

 int totalCount = api.getServiceList(0, 0).getTotalCount();
 

Parameters:

start - The start index (inclusive) of the result set of the query. Must not be negative.

end - The end index (exclusive) of the result set of the query. Must not be negative.

Returns:

The list of services.

Throws:

AuthleteApiException

updateService

Service updateService(Service service)
               throws AuthleteApiException

Update a service (= call Authlete's /service/update/{apiKey} API).

service.getApiKey() must return the correct API key of the service.

Parameters:

service - Information about a service to update.

Returns:

Information about the updated service.

Throws:

AuthleteApiException

getServiceJwks

String getServiceJwks()
               throws AuthleteApiException

Get the JWK Set of a service.

This method is an alias of getServiceJwks(true, false).

Returns:

JSON representation of the JWK Set of the service. null is returned when the service has registered neither content or URI of its JWK Set.

Throws:

AuthleteApiException

Since:

1.13

See Also:

RFC 7517: JSON Web Key (JWK)

getServiceJwks

String getServiceJwks(boolean pretty,
                      boolean includePrivateKeys)
               throws AuthleteApiException

Get the JWK Set of a service.

You can register either or both (1) the content of a JWK set and (2) the URI of a JWK set. The table below describes how registration combinations affect the response from this method. For example, the table indicates that the content of the JWK Set is returned with a status code 200 if both (content and URI) are registered.

Service JWK Set		Response
Content	URI	Status Code	Return Value	Exception
Registered	Registered	200 OK	JWK Set	Not Raised
Registered	Not Registered	200 OK	JWK Set	Not Raised
Not Registered	Registered	204 No Content	null	Not Raised
		302 Found *		Raised
Not Registered	Not Registered	204 No Content	null	Not Raised

302 Found is returned when the request URI and the registered JWK Set URI are different. In this case, Location header contains the registered JWK Set URI. If you need the value of the URI, catch AuthleteApiException and call getResponseHeaders().

Parameters:

pretty - true to get the JSON in pretty format.

includePrivateKeys - true to keep private keys in the JSON. false to remove private keys.

Returns:

JSON representation of the JWK Set of the service. null is returned when the service has registered neither content or URI of its JWK Set.

Throws:

AuthleteApiException

Since:

1.28

See Also:

RFC 7517: JSON Web Key (JWK)

getServiceConfiguration

String getServiceConfiguration()
                        throws AuthleteApiException

Get the configuration of the service in JSON format that complies with OpenID Connect Discovery 1.0.

This method is an alias of getServiceConfiguration(true).

Returns:

The configuration of the service in JSON format.

Throws:

AuthleteApiException

Since:

1.27

See Also:

OpenID Connect Discovery 1.0

getServiceConfiguration

String getServiceConfiguration(boolean pretty)
                        throws AuthleteApiException

Get the configuration of the service in JSON format that complies with OpenID Connect Discovery 1.0.

The value returned from this method can be used as the response body from /.well-known/openid-configuration. See "4. Obtaining OpenID Provider Configuration Information" in OpenID Connect Discovery 1.0 for details.

Parameters:

pretty - true to get the JSON in pretty format.

Returns:

The configuration of the service in JSON format.

Throws:

AuthleteApiException

Since:

1.28

See Also:

OpenID Connect Discovery 1.0

createClient

Client createClient(Client client)
             throws AuthleteApiException

Create a client (= call Authlete's /client/create API).

Parameters:

client - Information about a client to create.

Returns:

Information about a newly created client.

Throws:

AuthleteApiException

deleteClient

void deleteClient(long clientId)
           throws AuthleteApiException

Delete a client (= call Authlete's /client/delete/{clientId} API).

Parameters:

clientId - Client ID.

Throws:

AuthleteApiException

getClient

Client getClient(long clientId)
          throws AuthleteApiException

Get a client (= call Authlete's /client/get/{clientId} API).

Parameters:

clientId - The client ID.

Returns:

Information about the client.

Throws:

AuthleteApiException

getClientList

ClientListResponse getClientList()
                          throws AuthleteApiException

Get the list of client applications that belong to the service (= call Authlete's /client/get/list API).

This method uses the default range to limit the result set of the query. Use getClientList(int, int) to specify the range explicitly.

Returns:

The list of clients.

Throws:

AuthleteApiException

getClientList

ClientListResponse getClientList(String developer)
                          throws AuthleteApiException

Get the list of client applications that belong to the developer (= call Authlete's /client/get/list API with developer parameter).

When developer is null, the list of client applications that belong to the service is returned.

This method uses the default range to limit the result set of the query. Use getClientList(String, int, int) to specify the range explicitly.

Parameters:

developer - The developer of the targeted client applications.

Returns:

The list of clients.

Throws:

AuthleteApiException

getClientList

ClientListResponse getClientList(int start,
                                 int end)
                          throws AuthleteApiException

Get the list of client applications that belong to the service (= call Authlete's /client/get/list API with start and end parameters).

Parameters:

start - The start index (inclusive) of the result set of the query. Must not be negative.

end - The end index (exclusive) of the result set of the query. Must not be negative.

Returns:

The list of clients.

Throws:

AuthleteApiException

getClientList

ClientListResponse getClientList(String developer,
                                 int start,
                                 int end)
                          throws AuthleteApiException

Get the list of client applications (= call Authlete's /client/get/list API with developer, start and end parameters).

When developer is null, the list of client applications that belong to the service is returned. Otherwise, when developer is not null, the list of client applications that belong to the developer is returned.

The pair of start and end parameters denotes the range of the result set of the query. For example, if start is 5 and end is 7, the pair makes a range from 5 (inclusive) to 7 (exclusive) and the response will contain (at most) 2 pieces of client information, i.e., information about the 6th and the 7th applications (the index starts from 0).

If end - start is equal to or less than 0, getClients() method of the response returns null. But even in such a case, getTotalCount() method returns the total count. In other words, if you want to get just the total count, you can write the code as shown below.

 int totalCount = api.getClientList(developer, 0, 0).getTotalCount();
 

Parameters:

developer - The developer of the targeted client applications, or null to get the list of client applications of the entire service.

start - The start index (inclusive) of the result set of the query. Must not be negative.

end - The end index (exclusive) of the result set of the query. Must not be negative.

Returns:

The list of client applications.

Throws:

AuthleteApiException

updateClient

Client updateClient(Client client)
             throws AuthleteApiException

Update a client (= call Authlete's /client/update/{clientId} API).

client.getClientId() must return the correct client ID.

Parameters:

client - Information about a client to update.

Returns:

Information about the updated client.

Throws:

AuthleteApiException

getRequestableScopes

String[] getRequestableScopes(long clientId)
                       throws AuthleteApiException

Get the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/get/{clientId} API).

Parameters:

clientId - A client ID.

Returns:

null

Requestable scopes are not assigned to the client, meaning that the client can request any scopes supported by the service.

An empty array

The client cannot request any scopes, meaning that values included in the scope request parameter in authorization requests and token requests are all ignored.

An array of scope names

The array represents the set of scopes that the client is allowed to request.

Throws:

AuthleteApiException

Since:

1.34

setRequestableScopes

String[] setRequestableScopes(long clientId,
                              String[] scopes)
                       throws AuthleteApiException

Set the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/update/{clientId} API).

Calling this method with scopes=null has the same effect as calling deleteRequestableScopes(clientId).

Since the version 1.39, the Client class has extension property and information about "Requestable Scopes per Client" is included in the property. So, calling /client/update/{clientId} API is enough and recommended. In other words, calling /client/extension/requestable_scopes/update/{clientId} API is no longer recommended.

Known issue: The JSON parser used by the implementation of /client/extension/requestable_scopes/update/{clientId} API treats an empty array as null and it does not provide any configuration method to change the behavior. Until the JSON parser is replaced, passing an empty array to the API leads to the same result as passing null to the API.

Parameters:

clientId - A client ID.

scopes -

null

Requestable scopes assigned to the client are cleared. This results in that the client can request any scopes supported by the service.

An empty array

The client cannot request any scopes, meaning that values included in the scope request parameter in authorization requests and token requests are all ignored.

An array of scope names

The given array is used as the set of scopes that the client is allowed to request.

Returns:

The resultant set of requestable scopes. The value may be different from the one given to this method.

Throws:

AuthleteApiException

Since:

1.34

deleteRequestableScopes

void deleteRequestableScopes(long clientId)
                      throws AuthleteApiException

Clear the requestable scopes assigned to a client (= call Authlete's /client/extension/requestable_scopes/delete/{clientId} API).

Calling this method has the same effect as calling setRequestableScopes(clientId, null).

Parameters:

clientId - A client ID.

Throws:

AuthleteApiException

Since:

1.34

getGrantedScopes

GrantedScopesGetResponse getGrantedScopes(long clientId,
                                          String subject)

Get the set of scopes that a user has granted to a client application (call Authlete's /client/granted_scopes/get/{clientId} API).

A dedicated Authlete server provides a functionality to remember the set of scopes that a user has granted to a client application. A remembered set is NOT removed from the database even after all existing access tokens associated with the combination of the client application and the subject have expired. Note that this functionality is not provided by the shared Authlete server.

Parameters:

clientId - A client ID.

subject - A unique user identifier.

Returns:

Information about scopes granted to a client application by a user.

Since:

1.39

deleteGrantedScopes

void deleteGrantedScopes(long clientId,
                         String subject)

Delete DB records about the set of scopes that a user has granted to a client application (call Authlete's /client/granted_scopes/delete/{clientId} API).

Even if you delete records about granted scopes by calling this API, existing access tokens are not deleted and scopes of existing access tokens are not changed.

Please call this method if the user identified by the subject is deleted from your system. Otherwise, garbage data continue to exist in the database.

Parameters:

clientId - A client ID.

subject - A unique user identifier.

Since:

1.40

deleteClientAuthorization

void deleteClientAuthorization(long clientId,
                               String subject)
                        throws AuthleteApiException

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

Parameters:

clientId - The ID of the target client application.

subject - The subject (= unique identifier) of the end-user. Must not be null.

Throws:

AuthleteApiException

Since:

2.1

getClientAuthorizationList

AuthorizedClientListResponse getClientAuthorizationList(ClientAuthorizationGetListRequest request)
                                                 throws AuthleteApiException

Get a list of client applications authorized by the end-user.

Parameters:

request - Conditions to query the list. The subject property (= the unique identifier of the end-user) in the request must not be null.

Returns:

A list of client applications that have been authorized by the end-user.

Throws:

AuthleteApiException

Since:

2.1

updateClientAuthorization

void updateClientAuthorization(long clientId,
                               ClientAuthorizationUpdateRequest request)
                        throws AuthleteApiException

Update attributes of all existing access tokens issued to the client application by the end-user.

Parameters:

clientId - The ID of the target client application.

request - The subject (= unique identifier) of the end-user and new attribute values of access tokens. The subject property in the request must not be null.

Throws:

AuthleteApiException

Since:

2.1

getSettings

Settings getSettings()

Get the reference to the settings of this AuthleteApi implementation.

Returns:

The reference to the settings of this AuthleteApi implementation.

Since:

2.9