Skip to main content

OAuth 2.0 Authorization

OAuth 2.0 is an open standard for authorization defined in RFC 6749. It allows a resource owner (user) to provide a third-party client (application) secure delegated access to their data on a resource server without sharing their credentials.

APIMatic supports all the grant types defined in the OAuth 2 Standard in its editor and the Code Generation engine.

The SDKs generated by the Code Generation engine help developers in:

  • Obtaining consent from user
  • Acquiring access token
  • Refreshing tokens when they expire
  • Making authorized API calls

You can configure the API to use OAuth 2 from the Authentication page of the API editor.

oauth2-auth-settings

note

Full support for Implicit Grant is only available in AngularJS SDK because the grant is meant to be used in user-agent based applications.

Types

Grant typeDescription
Authorization CodeA redirection-based flow optimized for confidential clients. The client must be capable of interacting with the resource owner's user-agent and capable of receiving incoming requests (via redirection) from the authorization server.
ImplicitA redirection-based flow optimized for public clients known to operation at a particular redirection URI. The client must be capable of interacting with the resource owner's user-agent and capable of receiving incoming requests (via redirection) from the authorization server.
Resource Owner Password CredentialsA grant suitable for clients capable of obtaining resource owner's credentials. The resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application.
Client CredentialsA grant suitable for a confidential client that is requesting access to the protected resources under its control.

Scopes

The scopes define the types of permissions supported by the API. You must declare the scopes that can be used in the API here.

oauth2-auth-settings

Adding a scope

A scope is defined by the following fields.

FieldDescription
NameA unique user-friendly name or ID for the scope.
ValueThe "string" to use as scope when sending over the API.
DescriptionA text describing what the scope does.

Required scopes for endpoint

You can set the list of required scopes for an endpoint in the endpoint page.

oauth2-auth-settings

Settings

In order for OAuth 2 to work, the endpoints are needed:

  • Authorization endpoint: The authorization endpoint is used to interact with the resource owner and obtain an authorization grant.
  • Token endpoint: The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token.

These endpoints are defined by setting their server and route URL.

FieldDescription
OAuth2 Authorization ServerName of server which serves as the base URL for the Authorization endpoint.
Authorization RouteThe route for the Authorization endpoint. This must be a relative URL.
OAuth2 Access Token ServerName of server which serves as the base URL for the Token endpoint.
Access Token RouteThe route for the Token endpoint. This must be a relative URL.

Settings for Grant Types

Selective settings are applicable depending upon the OAuth 2 grant type used.

Grant TypeRequired Setting(s)
Authorization CodeAuthorization endpoint, Token endpoint
ImplicitAuthorization endpoint
Resource Owner Password CredentialsToken endpoint
Client CredentialsToken endpoint