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 revoked.

This API requires the create_longterm_token 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 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 Acquire access token via refresh token, as would normally be the case.

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 revoked.

This API requires the create_service_tokens 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 registered to allow long term tokens.

scopes:

The 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 Acquire access token via 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