Authentication and authorization with OAuth 2.0

Introduction

OP APIs use authentication and authorization flows based on OAuth and OpenID Connect. OAuth provides clients with "secure delegated access" to server resources on behalf of a resource owner, allowing resource owners (e.g. end users) to authorize third-party access to their resources without sharing or exposing their credentials.

Different APIs have different security needs, which is reflected in their selected method of authentication and authorization. The documentation of each API will describe the requirements in more detail.

For PSD2 auth flows, see the documentation for PSD2 APIs.

Always store your API keys and secrets securely!


Roles

OAuth defines four roles:

Resource Owner

The resource owner is the user who authorizes an application to access their resources. The application's access to the user's resource is limited to the "scope" of the authorization granted (e.g. read or write access).

Client

The client is the application that wants to access the user's resources. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.

Resource Server

The resource server (Service API) hosts the protected user resources.

Authorization Server

The authorization server (Authorization API) verifies the identity of the user then issues access tokens to the application.


Tokens

Depending on the grant type and the position of access flow, authorization endpoints respond with slightly different tokens.

A typical token response contains these fields:

FieldExplanation
token_typeType of the token (bearer, refresh, etc)
access_tokenRequested access token
scopeDefines the amount of access granted to this access token
statusToken status (approved, rejected, pending, etc.)
refresh_tokenToken for refreshing access token
refresh_token_expires_inValidity period for refresh token (in seconds)
refresh_token_issued_atIssue time (in seconds since epoch)
expires_inValidity period for access token (in seconds)
refresh_countNumber of times access token has been refreshed

Grant types

Authorization Code Grant

The Authorization Code Grant is used when an application needs to access resources owned by an end user. The flow implements strong user authentication and lets customers authorize TPP applications to access protected customer data.

The Authorization Code Grant is used with APIs whose security rating is Substantial.

Please note that each API making use of the Authorization Code Grant may require additional parameters or procedures before granting access to the API. These requirements will always be described together with the API in question.

Read more about Authorization Code Grant >

Client Credentials Grant

The OAuth Client Credentials grant is used when an application wants to access resources it owns, and which do not require acting on behalf of a user.

In our context, the Client Credentials grant is used as a means of identifying third parties in cases where strong end user identification is not required, and/or where end user consent is handled separately from the actual API interaction.

In practice, the client credentials grant is implemented by a token endpoint which returns an access token corresponding to the supplied API key and secret. Some APIs require extra attributes during token requests. For more information see corresponding API documentation.

Read more about OAuth 2.0 Client Credentials Grant >