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	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).
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).
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).
IntrospectionResponse	introspection(IntrospectionRequest request) Call Authlete's /auth/introspection API.
RevocationResponse	revocation(RevocationRequest request) Call Authlete's /auth/revocation 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.
Client	updateClient(Client client) Update a client (= call Authlete's /client/update/{clientId} API).
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

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

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