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.
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.
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=(client_id) &tenant_id=(name of your utility, e.g eneco, viesgo)
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=(client_id) &client_secret=(client_secret) &grant_type=authorization_code &code=(code)" https://api.toon.eu/token
curl -v -k https://api.toon.eu/authorize?response_type=token &redirect_uri=(redirect_url) &client_id=(client_id) &tenant_id=
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=(client_id) &client_secret=(client_secret) &grant_type=refresh_token &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=(client_id) &client_secret=(client_secret)" https://api.toon.eu/revoke