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

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.toonapi.com/toon/api/v1/

Client: The application requesting access to a resource server on behalf of the resource owner and with its authorization (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.toonapi.com/[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 where the client is a web browser that sends requests to the resource server via Javascript.

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.

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: 

  • 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 

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 in secret. In this method, once the user authorizes the Consumer App's authorization request, the app gets the Access Token directly. 

curl -v -k 
    https://api.toonapi.com/authorize?response_type=token
        &redirect_uri=<REDIRECT_URL>
        &client_id=<CLIENT_ID>

Password 

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

Refresh 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

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 "token=<ACCESS_TOKEN>
        &client_id=<CLIENT_ID>
        &client_secret=<CLIENT_SECRET>"
    https://api.toonapi.com/revoke