OAuth API Documentation

What is an OAuth 2.0 Grant Type?

The OAuth 2.0 framework describes a nummber of grants (methods) for a client application to acquire an access token (which represents a user’s permission for the client to access their data) which can be used to authenticate a request to an API endpoint.

Each grant type is optimized for a particular use case, whether that’s a web app, a native app, a device without the ability to launch a web browser, or server-to-server applications.

The most common OAuth 2.0 grant types we support are:

• Authorization code grant
• Implicit grant
• Client Credentials grant
• Password grant
• Refresh Token grant

Here we are going to describes each of above grant with their appropriate use cases and snippet codes.

Before begining, here are the most common OAuth terms that we are going to use:

• Resource Owner (a.k.a. User):
  An entity capable of granting access to it's protected resources. If this entity is a person, it is referred to as an end-user.

• Resource Server (a.k.a. API server / OAuth provider):
  The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

• Client :
  An application making protected resource requests on behalf of the resource owner and with its authorization. The term client does not imply any particular implementation characteristics (e.g. whether the application executes on a server, a desktop, or other devices).

• Authorization Server :
  The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Grant Types

Authorization Code Grant

The Authorization Code Grant Type is probably the most common of the OAuth 2.0 grant types that you’ll encounter. It is used by both web apps and native apps to get an access token after a user authorizes an app.

You can read more about Authorization Code Grant Here: Authorization Code Grant

Implicit Grant

Implicit grant flow is for clients that are implemented entirely using javascript and are running in resource owner's browser. You do not need any server side code to use this flow. Then, if everything happens in resource owner's browser it makes no sense to issue auth code & client secret anymore, because token & client secret will still be shared with resource owner. Including auth code & client secret just makes the flow more complex without adding any more real security.

You can read more about Implicit Grant Here: Implicit Grant

Client Credentials Grant

Client Credentials grant can be used for machine to machine authentication. In this grant a specific user is not authorized but rather the credentials are verified and a generic access_token is returned.

You can read more about Client Credentials Grant Here: Client Credentials Grant

Password Grant

The resource owner password (or "password") grant type is mostly used in cases where the app is highly trusted. In this configuration, the user provides their resource server credentials (username/password) to the client app, which sends them in an access token request.

You can read more about Password Grant Here: Password Grant

Refresh Token Grant

A Refresh Token allows the application to issue a new Access Token or ID Token without having to re-authenticate the user. This will work as long as the Refresh Token has not been revoked

You can read more about Refresh Token Grant Here: Refresh Token Grant