Platform of Trust Platform Design Guide
Developer PortalAPI DocsOntology
  • Purpose and scope
  • Developer eXperience Strategy
  • Suggest changes
  • API Requests
    • Request validation
    • Response codes used
    • Error handling
  • General API guidelines
    • Performance
    • Documentation
    • Data models used
    • Use HATEOAS
    • Use HTTP Methods
    • Dates and time
    • Naming conventions
    • Pagination, partial response and sorting
    • API Testing
  • API Headers
    • Mandatory elements & behaviour
    • Rate limiting information
  • API Security
    • Authentication and authorization
    • SSL everywhere - all the time
  • API versioning guidelines
    • Versioning Rules
    • Breaking changes
    • Non-breaking changes example
    • Retirement process
    • Add new API to documentation
    • Add new endpoint
  • API Migration Policies
    • Deprecating API
    • Sunsetting API
    • Blackout Testing
    • Migration Email Template
    • API Blackout Test Email Template
    • API Deprecation Email
    • Deprecating an older API
  • Ontologies
    • About ontologies
    • Web Ontology Language, OWL
    • Ontology editor
    • Edit ontology
    • Add new subclass
    • Naming convention logic
    • Extending the ontology
  • Design Guideline
    • Colors
    • Typography
    • Grids and Space
    • Input forms - Text field
    • Input forms - Text area
    • Buttons
    • Checkbox
    • Radio buttons
    • Date picker
    • Form control - Single select
    • Toggle
    • Pagination
    • Status pills
    • Tables
    • Effects
    • Dialogues
Powered by GitBook
On this page
  • Basic rule for error handling
  • OAuth2 background and options
  • Use authorization code flow
  • OAuth2 authorization code flow example
  • /auth/v2/
  • Authorize

Was this helpful?

  1. API Security

Authentication and authorization

REST APIs should be stateless. Every request should be self-sufficient and must be fulfilled without knowledge of the prior request. This happens in the case of Authorizing a user action.

Previously, developers stored user information in server-side sessions, which is not a scalable approach. For that reason, every request should contain all the information of a user (if it’s a secure API), instead of relying on previous requests.

This doesn’t limit APIs to a user as an authorized person, as it allows service-to-service authorization as well. For user authorization, JWT (JSON Web Token) with OAuth2 provides a way to achieve this. Additionally, for service-to-service communication, try to have the encrypted API-key passed in the header.

Basic rule for error handling

A 401 Unauthorized response should be used for missing or bad authentication, and a 403 Forbidden response should be used afterwards, when the user is authenticated but isn’t authorized to perform the requested operation on the given resource.

Use Access and Refresh Tokens

Modern stateless, RESTful APIs implement authentication with tokens. This eliminates the need to handle sessions and cookies on a now stateless server, and makes it really easy to debug network requests by simply utilising the Authorization header (or even an access_token query param).

Access Tokens

The access token is used for authenticating all future API requests, has a short life span and can’t be revoked.

Refresh Tokens

The refresh token is returned in the initial login response, but it is hashed and stored in the database with an expiry timestamp and relationship to the user. This acts as a long-life, password-like secret token, which can be used to request a new short-life JWT access tokens. Refresh tokens also extend their life every time they are used for renewal, meaning that a user doesn’t need to log in again if they continually use the service.

TODO: Describe with code example how authentication and authorization is implemented in PoT context

OAuth2 background and options

OAuth 2.0 specification defines 4 types of authorization flows:

  • Authorization Code

  • Resource Owner Password Credentials

  • Implicit

  • Client Credentials

Implicit and Client Credentials are flows typically reserved for special types of clients. More specifically,

  • Implicit: Single-page Javascript Web Applications (for example, Google Fonts)

  • Client Credentials: Non-interactive programs for machine-to-machine communications (for example, background services and daemons)

As for other clients, depending on their trustworthiness, they can use the following flows:

  • Authorization Code or Resource Owner Password Credentials: Highly trusted apps (first-party apps)

  • Authorization Code: Less trusted apps (third-party apps requesting access to PoT platform)

Use authorization code flow

Loosely speaking, PoT is a platform where third-party applications and services can access its resources, thus we use authorization code flow.

OAuth2 authorization code flow example

Step 1: Authorization Code Link

/auth/v2/

GET

Path Parameters

Name
Type
Description

string

Step 2: User Authorizes Application

Authorize

GET

Path Parameters

Name
Type
Description

string

PreviousRate limiting informationNextSSL everywhere - all the time

Last updated 5 years ago

Was this helpful?