Extended authorization ====================== Obtain long term refresh token ------------------------------ This API can be used to obtain an refresh token with infinite life time and is primarily intended for applications that need permanent account access where reauthentication is not possible/ practical (e.g. server applications). Requesting a token multiple times will create multiple tokens, even for the same User/client combination. Tokens that are no longer needed should be :ref:`revoked `. This API requires the `create_longterm_token` :ref:`scope `. :: POST $base_url/api/v1/ext_auth/request_longterm_token Authorization: Bearer rGnMQIWz Content-type: application/json { scopes: ["query_account"] } ==> Content-type: application/json { refresh_token: "twSYH1dxoyTiylVDV8beCTun" } Parameters ^^^^^^^^^^ Parameters are encoded as JSON object with the following keys: :scopes: Optional. The :ref:`scopes ` to be included in the created refresh token. Only scopes that are present in the bearer token used to access this API can be requested. If not specified the default scopes for the client that are also granted to the used bearer token will be used. :app_infos: Optional. Provide text that helps identify where this token orignated from/ is used (e.g. a hostname to disambiguate multiple devices) Response ^^^^^^^^ The response is a JSON object currently containing a single key: the refresh token :refresh_token: The newly created refresh token .. note:: In order to eventually clean up discarded tokens that were not properly revoked the token *will* expire if it was not used at least once within a year. However this refresh token will never change when it is used to obtain an access token via :ref:`api_oauth2_access_token_from_refresh_token`, as would normally be the case. .. _api_long_term_service_token: Obtain long term service token ------------------------------ This is a specialized API that will only be available to EGR internal clients. It's purpose is to obtain an refresh token with infinite life time for another registered client. With this refresh token it is possible to act on behalf the user indefinitely (unless the token is revoked). Requesting a token multiple times will create multiple tokens, even for the same User/client combination. Tokens that are no longer needed should be :ref:`revoked `. This API requires the `create_service_tokens` :ref:`scope `. :: POST $base_url/api/v1/ext_auth/request_service_token Authorization: Bearer rGnMQIWz Content-type: application/json { client_id: "XYZ-EXAMPLE-CLIENT", scopes: ["query_account"] } ==> Content-type: application/json { refresh_token: "twSYH1dxoyTiylVDV8beCTun" } Parameters ^^^^^^^^^^ Parameters are encoded as JSON object with the following keys: :client_id: OAuth client id of the client for which the refresh token should be generated. The client must be specifically :ref:`registered ` to allow long term tokens. :scopes: The :ref:`scopes ` to be included in the created refresh token. If not specified the default for the given client will be used. :app_infos: Optional. Provide text that helps identify where this token orignated from/ is used (e.g. a hostname to disambiguate multiple devices) .. important:: Only the *minimum* of scopes that is needed for the service to operate should be requested here Response ^^^^^^^^ The response is a JSON object currently containing a single key: the refresh token :refresh_token: The newly created refresh token .. note:: In order to eventually clean up discarded tokens that were not properly revoked the token *will* expire if it was not used at least once within a year. However this refresh token will never change when it is used to obtain an access token via :ref:`api_oauth2_access_token_from_refresh_token`, as would normally be the case. Get information about token --------------------------- This API allows to query information about an existing oauth2 access or refresh token, most notably the associated scopes as well as the expiry date. No `Authorization: Bearer ...` header is necessary for this API (as the token is passed via request body to support different kinds of token) :: POST $base_url/api/v1/ext_auth/token_info Content-type: application/json { "token": "vcbYvsvyIPEidX3rxtRrbJqi3I6ydj" } ==> Content-type: application/json { "client_id": "WAM-APITEST", "expires": "2018-08-20T16:09:12+00:00", "scopes": [ "query_account", "modify_account" ] } Parameters ^^^^^^^^^^ :token: Token for which information should be queried. Can be either an access token, or a refresh token. Response ^^^^^^^^ A JSON object with the following properties: :client_id: Client id associated with the token :expires: Expiry date of the token :scopes: List of scopes associated with the token Get access token for the "public" user -------------------------------------- This API returns an access token used to access data that was made available publicly. No `Authorization: Bearer ...` header is necessary for this API :: GET $base_url/api/v1/ext_auth/public_user_token?client_id=WAM-APITEST ==> Content-type: application/json { "access_token": "BzMsjVjslWAWNuZOBnjfXOY2oJVGul", "expires_in": 3600 } Parameters ^^^^^^^^^^ :client_id: Id of the client that wants to use the token Response ^^^^^^^^ A JSON object with the following properties: :access_token: A fresh access token for the "public" user account using the given client :expires_in: Seconds until the token expires Determine if token belongs to the "public" user ----------------------------------------------- This API allows to query information about an existing oauth2 access or refresh token, most notably the associated scopes as well as the expiry date. No `Authorization: Bearer ...` header is necessary for this API :: POST $base_url/api/v1/ext_auth/is_public_user_token Content-type: application/json { "token": "vcbYvsvyIPEidX3rxtRrbJqi3I6ydj" } ==> Content-type: application/json { "is_public_user_token": true } Parameters ^^^^^^^^^^ :token: Token that should be queried (currently only access tokens are supported) Response ^^^^^^^^ A JSON object with the following properties: :is_public_user_token: Boolean indicating whether this token is associated with the "public" user account