Get everything you need to get started today!Download it now
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 application.
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.toonapi.com/toon/api/v1/
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.toonapi.com/[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:
The access tokens currently expire in one hour. 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 after its lifetime.
Register as a client
Before the client retrieves data from a resource server using OAuth2, the client needs to register in our API. During the client registration, the client will specify the application name and several other parameters. After successful registration, confidential clients will receive client credentials that include the credentials listed below:
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 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).
The client can use these credentials to log into the Toonapi website. In your application portal you can find your application keys and edit your Callback URL, the redirection URL you receive 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:
- From the application make a call to ToonAPI as follows:
curl -v -k https://api.toonapi.com/authorize?response_type=code &redirect_uri=<REDIRECT_URL> &client_id=<CLIENT_ID>
- From the ToonAPI website's login page, the end user needs to provide his credentials, and then a redirect will be performed to the redirect_uri provided before with a code.
- The application can now use the 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.toonapi.com/token
curl -v -k https://api.toonapi.com/authorize?response_type=token &redirect_uri=<REDIRECT_URL> &client_id=<CLIENT_ID>
In this type, the user’s credentials are sent with the initial request. While its seems contradictory to the purpose OAuth (to avoid giving away your password to a third-party application) but it doesn’t because this method is supposed to be used by the applications that are owned by the resource server itself, and not by any other third party. You can easily get a token providing the user credentials.
note: You won't use this method in your finished application because you don't want to store the user credentials in your application.
curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password &client_id=<CLIENT_ID> &client_secret=<CLIENT_SECRET> &username=<USERNAME> &password=<PASSWORD>" https://api.toonapi.com/token
Resource owner (i.e. user) is not involved in this method. Here, the Consumer App uses its Client ID and Client Secret to get an Access Token. This method is supposed to be used when the app needs to access its own data rather than the user’s protected data.
curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=<CLIENT_ID> &client_secret=<CLIENT_SECRET> &grant_type=client_credentials" https://api.toonapi.com/token
As explained above, with the access token you might get a refresh token as well. 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.toonapi.com/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 "token=<ACCESS_TOKEN> &client_id=<CLIENT_ID> &client_secret=<CLIENT_SECRET>" https://api.toonapi.com/revoke