Authentication and authorization with OAuth 2.0
Here you can find documentation and examples for end user authentication and authorization.
This page is currently in development so some changes are expected.
Authentication to our APIs is done via OAuth. OAuth is an authorization framework that enables applications to get limited access to end user's resources without giving them user passwords.
OAuth provides to clients a "secure delegated access" to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.
OAuth provides different authentication and authorization flows based on the use case and the type of client application. When developing your application you should be aware the differences between OAuth Grants and select suitable flow based on your application design.
Based on the API security level different grant types are required when accessing our APIs. Read from API documentation which grant is required when accessing the API.
Allways store your api keys and secrets in secure way!
OAuth defines four roles:
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).
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.
The resource server (Service API) hosts the protected user resources.
The authorization server (Authorization API) verifies the identity of the user then issues access tokens to the application.
Depending on a grant type and the position of access flow, authorization endpoints respond with slightly different tokens.
A typical token response contains these fields.
- token_type - Type of the token (bearer, refresh, etc)
- access_token - Requested access token
- scope - Defines the amount of access granted to this access token
- status - Status of the token (approved, rejected, pending etc)
- refresh_token - Token for refreshing access token
- refresh_token_expires_in - Validity period for refresh token (in seconds)
- refresh_token_issued_at - Issue time (in seconds since epoch)
- expires_in - Validity period for access token (in seconds)
- refresh_count - Number of times access token has been refreshed
The OAuth 2.0 framework specifies several grant types for different use cases. Here you can find explanations and examples for different grants that are used with OP APIs.
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 also 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.
Resource Owner Credentials 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.