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