Package com.authlete.common.api

Interface AuthleteApi

  • public interface AuthleteApi
    Authlete API.
    Author:
    Takahiko Kawasaki

    • Method Detail

      • getTokenList

        TokenListResponse getTokenList()
                        throws AuthleteApiException
        Get the list of access tokens that are associated with the service (= call Authlete's /auth/token/get/list API).

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

        Returns:
        The list of access tokens.
        Throws:
        AuthleteApiException
        Since:
        2.29

      • getTokenList

        TokenListResponse getTokenList​(String clientIdentifier,
                               String subject)
                        throws AuthleteApiException
        Get the list of access tokens (= call Authlete's /auth/token/get/list API with clientIdentifier and subject).

        When both clientIdentifier and subject are null, the list of access tokens that are associated with the service is returned.

        When clientIdentifier is null but the subject is not null, the list of access tokens that are associated with the subject is returned.

        When clientIdentifier is not null but the subject is null, the list of access tokens that are associated with the client application is returned.

        When neither clientIdentifier nor subject is null, the list of access tokens that are associated with the client application and the subject is returned.

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

        Parameters:
        clientIdentifier - The identifier of the client (client ID or client ID alias) associated with the targeted access tokens, or null.
        subject - The subject of the targeted access tokens, or null.
        Returns:
        The list of access tokens.
        Throws:
        AuthleteApiException
        Since:
        2.29

      • getTokenList

        TokenListResponse getTokenList​(int start,
                               int end)
                        throws AuthleteApiException
        Get the list of access tokens that are associated with the service (= call Authlete's /auth/token/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 access token information, i.e., information about the 6th and the 7th access tokens (the index starts from 0).

        If end - start is equal to or less than 0, getAccessTokens() 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.getTokenList(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 access tokens.
        Throws:
        AuthleteApiException
        Since:
        2.29

      • getTokenList

        TokenListResponse getTokenList​(String clientIdentifier,
                               String subject,
                               int start,
                               int end)
                        throws AuthleteApiException
        Get the list of access tokens (= call Authlete's /auth/token/get/list API with clientIdentifier, subject, start and end parameters).

        When both clientIdentifier and subject are null, the list of access tokens that are associated with the service is returned.

        When clientIdentifier is null but the subject is not null, the list of access tokens that are associated with the subject is returned.

        When clientIdentifier is not null but the subject is null, the list of access tokens that are associated with the client application is returned.

        When neither clientIdentifier nor subject is null, the list of access tokens that are associated with the client application and the subject 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 access token information, i.e., information about the 6th and the 7th access tokens (the index starts from 0).

        If end - start is equal to or less than 0, getAccessTokens() 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.getTokenList(clientIdentifier, subject, 0, 0).getTotalCount();
        Parameters:
        clientIdentifier - The identifier of the client (client ID or client ID alias) associated with the targeted access tokens, or null.
        subject - The subject of the targeted access tokens, or null.
        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 access tokens.
        Throws:
        AuthleteApiException
        Since:
        2.29

      • createService

        Service createService​(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​(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​(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)

      • 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

      • dynamicClientGet

        ClientRegistrationResponse dynamicClientGet​(ClientRegistrationRequest request)
                                     throws AuthleteApiException
        Get a dynamically registered client (= call Authlete's /client/registration/get API). This method can be used to implement a client registration management endpoint that complies with RFC 7592 (OAuth 2.0 Dynamic Client Registration Management Protocol).
        Parameters:
        request - Request parameters passed to the API.
        Returns:
        Response from the API.
        Throws:
        AuthleteApiException
        Since:
        2.41

      • dynamicClientUpdate

        ClientRegistrationResponse dynamicClientUpdate​(ClientRegistrationRequest request)
                                        throws AuthleteApiException
        Update a dynamically registered client (= call Authlete's /client/registration/update API). This method can be used to implement a client registration management endpoint that complies with RFC 7592 (OAuth 2.0 Dynamic Client Registration Management Protocol).
        Parameters:
        request - Request parameters passed to the API.
        Returns:
        Response from the API.
        Throws:
        AuthleteApiException
        Since:
        2.41

      • dynamicClientDelete

        ClientRegistrationResponse dynamicClientDelete​(ClientRegistrationRequest request)
                                        throws AuthleteApiException
        Delete a dynamically registered client (= call Authlete's /client/registration/delete API). This method can be used to implement a client registration management endpoint that complies with RFC 7592 (OAuth 2.0 Dynamic Client Registration Management Protocol).
        Parameters:
        request - Request parameters passed to the API.
        Returns:
        Response from the API.
        Throws:
        AuthleteApiException
        Since:
        2.41

      • 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​(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

      • 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

      • refreshClientSecret

        ClientSecretRefreshResponse refreshClientSecret​(long clientId)
                                         throws AuthleteApiException
        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 updateClientSecret method.
        Parameters:
        clientId - The client ID of a client.
        Returns:
        A response from Authlete's /api/client/secret/refresh API.
        Throws:
        AuthleteApiException
        Since:
        2.11

      • refreshClientSecret

        ClientSecretRefreshResponse refreshClientSecret​(String clientIdentifier)
                                         throws AuthleteApiException
        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 updateClientSecret method.
        Parameters:
        clientIdentifier - The client ID or the client ID alias of a client.
        Returns:
        A response from Authlete's /api/client/secret/refresh API.
        Throws:
        AuthleteApiException
        Since:
        2.11

      • updateClientSecret

        ClientSecretUpdateResponse updateClientSecret​(long clientId,
                                              String clientSecret)
                                       throws AuthleteApiException
        Update the client secret of a client. If you want to have the Authlete server generate a new value of the client secret, use refreshClientSecret method.

        Valid characters for a client secret are A-Z, a-z, 0-9, -, and _. The maximum length of a client secret is 86.

        Parameters:
        clientId - The client ID of a client.
        clientSecret - The new value of the client secret.
        Returns:
        A response from Authlete's /api/client/secret/update API.
        Throws:
        AuthleteApiException
        Since:
        2.11

      • updateClientSecret

        ClientSecretUpdateResponse updateClientSecret​(String clientIdentifier,
                                              String clientSecret)
                                       throws AuthleteApiException
        Update the client secret of a client. If you want to have the Authlete server generate a new value of the client secret, use refreshClientSecret method.

        Valid characters for a client secret are A-Z, a-z, 0-9, -, and _. The maximum length of a client secret is 86.

        Parameters:
        clientIdentifier - The client ID or the client ID alias of a client.
        clientSecret - The new value of the client secret.
        Returns:
        A response from Authlete's /api/client/secret/update API.
        Throws:
        AuthleteApiException
        Since:
        2.11

      • 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

      • updateClientLockFlag

        void updateClientLockFlag​(String clientIdentifier,
                          boolean clientLocked)
                   throws AuthleteApiException
        Update the lock flag of a client application.
        Parameters:
        clientIdentifier - The client ID or the client ID alias of a client application.
        clientLocked - The value to which this request updates the lock flag of a client application.
        Throws:
        AuthleteApiException
        Since:
        3.10