Authentication

What is OAuth?

OAuth is an open standard for authorization and provides a method for clients to access server resources on behalf of a resource owner, such as a different client or an end-user. It also provides a process for end-users to authorize third-party access to their server resources without sharing their credentials, typically a username and password pair, using user-agent redirections. In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server by giving a different set of credentials (not the resource owner’s credentials) to access the resource. In OAuth, the client will obtain an access token from the authorization server which can be used to access server resources on behalf of the resource owner. The resource owner credentials will not be exposed to third-party applications.
 

Roles

• Resource owner: An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
• Resource server: The server hosting the protected resources. The resource server will grant access to protected resources if requests contain an access token. In our case, this would be ToonAPI endpoint: https://api.toon.eu/toon/v3
• Client: The application requesting access to a resource server on behalf of the resource owner and with its authorization (the client can be your PHP website, a Javascript application, or your mobile application).
• Authorization server: The server issuing the access token to the client after successful authentication with the resource owner. This token will be used for the client to request the resource server. This is: https://api.toon.eu/[token,authorize]
   

Tokens

Tokens are random strings generated by the authorization server after successful authentication with the resource owner, which will be used by clients to request resources from the resource server to obtain authorization for the particular resource. There are two types of tokens:

• Access token: Of the two tokens, the access token is more important because it protects the user data from being accessed by a third-party application. You will need to send this token as header (Authorization: Bearer xxxxxxx) when invoking ToonAPI endpoints. It has a limited lifetime, which is defined by the authorization server. It must be kept as confidential as possible, but this will not always be possible when the client is a web browser that sends requests to the resource server via Javascript. When requesting an access token, it will include the 'expires_in' field, which indicates the number of seconds before the access token expires.
• Refresh token: This token is issued with the access token, but unlike the latter, it is not sent in each request. The function of the refresh token is to obtain another access token when the current access token expires. The refresh token could also expires, it will include the refresh_token_expires_in field, which indicates the number of seconds before the refresh token expires.
   

Register as a client

Before the client retrieves data from a resource server using OAuth2, the client needs to register at our API. During the client registration, the client will specify the application name and a callbackURL. After successful registration, confidential clients will receive client credentials that include the following:

• Client ID: A unique string representing registration information provided by the client.
• Client secret: A secret key that must be kept confidential, and which the client can use to get the access token from the authorization server. Once you are registered to use the ToonAPI you will receive a pair of keys called client ID and client secret. These keys are fundamental to the OAuth protocol to get a token which will finally provide you access to protected resources (in this case, API endpoints). In your application portal you can find your application keys and edit your Callback URL. This is the redirection URL with which you receive an authorization code and access token.
   

For applications with a browser capability:

Authorization code

Our API issues an authorization code once the consumer apps authorization request is approved by the user. With the authorization code, the consumer app can request an access token. Here's how this works:

Make a call from the application to the ToonAPI as follows:

curl -v -k
    https://api.toon.eu/authorize?response_type=code
        &redirect_uri=<redirect_url>
        &client_id=<consumer_key>
        &tenant_id=eneco

From December 2019 onwards, Eneco users are required to use the “mijn Eneco” login to access their Toon, use the following call from the application to use the “mijn Eneco” as identity source:

curl -v -k
    https://api.toon.eu/authorize?response_type=code
        &redirect_uri=<redirect_url>
        &client_id=<consumer_key>
        &issuer=identity.toon.eu
        &tenant_id=eneco

From the ToonAPI website's login page, the end user needs to provide his credentials. A redirect will then be performed to the redirect_uri provided before with a code. The application can now use that code and the application key pair to get an access token that looks like this:

curl -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d  "client_id=<consumer_key>
        &client_secret=<consumer_secret>
        &grant_type=authorization_code
        &redirect_uri=<redirect_uri>
        &tenant_id=eneco
        &code=<code>"
    https://api.toon.eu/token 

Again, in this call, when users have logged in via "Mijn Eneco", add the issuer to this request:

curl -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d  "client_id=<consumer_key>
        &client_secret=<consumer_secret>
        &grant_type=authorization_code
        &issuer=identity.toon.eu
        &redirect_uri=<redirect_uri>
        &tenant_id=eneco
        &code=<code>"
    https://api.toon.eu/token 

Implicit

In this type, the client secret is not involved. This is mostly used for mobile apps and web browser-based apps (Javascript apps, etc.) where the client secret cannot be kept secret. With this method, the app gets the access token directly once the user authorizes the consumer app's authorization request.

curl -v -k 
    https://api.toon.eu/authorize?response_type=token
        &redirect_uri=<redirect_url>
        &client_id=<consumer_key>
        &tenant_id=eneco

This type is not supported for "mijn Eneco" users.

Refresh token

As explained above, you might get a refresh token with your access token. You can use this token to get a new access token when the current one expires. This is useful as there is no need to ask for the user credentials again.

curl -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d "client_id=<consumer_key>
        &client_secret=<consumer_secret>
        &grant_type=refresh_token
        &refresh_token=<refresh_token>"
    https://api.toon.eu/token

In case the issuer is provided during the token creation (/token or /authorize), use the following call to refresh a token.

curl -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d "client_id=<consumer_key>
        &client_secret=<consumer_secret>
        &grant_type=refresh_token
        &issuer=identity.toon.eu
        &refresh_token=<refresh_token>"
    https://api.toon.eu/token

Revoke tokens

After issuing an access token, a user or an admin can revoke it in case of theft or a security violation. Once revoked, the access token and corresponding refresh token will be invalidated. You can do this by calling the revoke API endpoint:

curl -v -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d "access_token=<access_token>
        &client_id=<consumer_key>
        &client_secret=<consumer_secret>"
    https://api.toon.eu/revoke

To revoke a refresh token, call the the revoke API endpoint with as following:

curl -v -k -X POST 
    -H "Content-Type: application/x-www-form-urlencoded"
    -d "refresh_token=<refresh_token>
        &client_id=<consumer_key>
        &client_secret=<consumer_secret>"
    https://api.toon.eu/revoke

Note that when the tokens were created with the issuer to the token or authenticate endpoint, the issuer has to be provided here as well.

For Headless applications

For federated users it is required to have an UI to generate tokens. To be able to support headless applications (for example a raspberryPI integrated with the ToonAPI) we offer the option to generate a long-lived access (10 year) token. This is currently only supported for users logging in with a “mijn Eneco” account.

To generate an access token, use the following link filled in with your generated client_id in a webbrowser:

https://api.toon.eu/toonapi-accesstoken?tenant_id=eneco&client_id=<consumer_key>