Help

2 min read

Best practices for BFC API design

Overview

The purpose of this document is to highlight the key areas of consideration when developing Backend-For-Client (BFC) APIs against the Poq Platform. It should act as a guide to help Poq partners deliver a secure and stable solution for their clients.

Security guidelines

Communications

It is crucial that HTTP communications between the App, BFC, Poq Platform, and any third party systems are secure. Ensure that:

  • Communications use TLS security version 1.2 or above.
  • APIs use SHA-256 SSL Certificates
  • Communications take place over SSL.

You should also:

  • Allow TLS protocol to negotiate the highest available version automatically.
  • Make use of the Authorization header for passing Access Tokens.

Logging

Logging can often be the source of data leakage of PII and other sensitive data. Ensure that:

  • Usernames, passwords, and email addresses, or any other Personally Identifiable Information are not logged.
  • Other sensitive credentials, such as API Keys and Client IDs are not logged.
  • Logs can only be accessed securely. They must not be accessible to an unauthorized party.

Least Privilege

Least Privilege is the principle that any given user, program, or process should only have the absolute minimum privileges required to complete its function. This enables tighter control of user access and tracking. Ensure that:

  • User credentials, access tokens, client IDs, authorization keys, or any other credentials cover no more than the minimum scope required to facilitate the implementation.
  • The BFC provides endpoints that allow clients to request the required scopes for a given task or feature.

Credentials

It is of utmost importance that credentials are not exposed to any parties whom they do not concern. Ensure that:

  • User passwords are not stored in any form (encrypted or otherwise) within the BFC solution.
  • User passwords must not be stored unless otherwise required.
  • If user passwords must be stored, they must be encrypted, or kept as a derived secret key. (For example, as Access & Refresh tokens.)
  • Refresh tokens are single-use. A new refresh token must be generated after usage.
  • Login endpoints are provided for solutions that enable user authorization; the Poq Platform does not provide any login endpoints other than management of Access & Refresh tokens.

You should also:

  • Defer to the Poq Platform or third party Client APIs to generate and manage derived keys using the Access & Refresh token flow defined in the Poq Platform documentation.

You should not:

  • Store user password in any form (encrypted or otherwise) within the BFC solution.

Development

Strict security is important even during the development phase of a BFC solution. Ensure that:

  • Any secret keys for infrastructure are not submitted to version control platforms (e.g. GitHub)
  • Secret keys for infrastructure can be revoked and rendered inactive in the event of exposure.

You should:

  • Apply the principle of least privilege to all members of the project team.
  • Make use of secret management software within the team to share secret keys & other credentials.