Secure Design Requirements
Last updated
Last updated
Below are the Secure Design Requirements which are referred to in the BrightPay API Legal Agreement. If you intend your Application (referred to in the legal agreement as the “API Client”) to connect to the API, your solution must adhere to these requirements as a minimum.
It may be helpful to define some terms
Customer means a user of both your system and BrightPay - the Customer wants to move data between the two systems (your system and BrightPay). In the legal agreement the Customer is referred to as the “Account Holder”. Note the term Customer refers to an individual user rather than multiple users belonging to a company.
The Client ID and Secret are credentials supplied by Bright, unique to your Application to allow integration. The Secret must be kept secure.
The diagram below shows a Customer’s Device, which could be a pc or mobile device running a web browser or an app/thick client. The Application, as defined above, is your application. The Application DB is your Application’s database. BrightID is Bright’s Authentication provider (where Bright customers log in). The BrightPay API is the endpoint that your Application will send information to and from.
As part of the integration your Application must display a “Login to Bright” button that when clicked must redirect the Customer to a BrightID Login URL. When constructing the BrightID Login URL you will use the Client ID and other details supplied by Bright.
The Authentication flow will work as follows
The Customer will click on the “Login to Bright” button displayed in your Application in their browser
The Customer’s browser will be redirected to BrightID
The Customer will log in to BrightID using their Bright account credentials
The Customer’s browser will then be redirected to your Application.
Your Application will, on receiving the redirection, extract an Authorization Code from the URL
Your Application will then send the Authorisation Code to BrightID (along with the Bright supplied Client ID and Secret), where it will be exchanged for a Refresh Token and an Access Token. The tokens are then returned to your Application
The Access Token can be used to communicate with the BrightPay API on behalf of the Customer. The Refresh Token can be used to get new Access Tokens (when the existing Access Token is close to time out). You may decide that your Application will store the Refresh Token in a database for future use.
With this in mind, your solution must adhere to the following security requirements:
The Customer’s Device (or whatever client is running on it) must not have access to the Secret, Authorisation Codes or Access and Refresh Tokens. This information should remain securely stored in your Application (server side);
The Customer’s Device (or whatever client is running on it) will display an Integration Button to log in to BrightID. On arriving at BrightID, the customer may be challenged for their Bright username and password. The client software running on the customer’s device must not intercept, store or record these credentials. The login process must occur in a browser outside your Client software or Application and the BrightID webpage must not be framed;
The Secret supplied by Bright must be securely stored server-side. The Secret should ideally be stored in a secure key vault to be access programmatically. The Secret must not stored in a source control system alongside the Application’s source code or held in the Application’s database;
If the Refresh Token is stored in the Database and must be stored securely with access to it carefully controlled (principle of least privileged access);
Care must be taken that any Refresh and Access Tokens are only used by the Customer they have been issued to;
All communication must be over HTTPs, TLS v1.2 minimum, v1.3 preferred to future-proof;
Your Application’s security must be kept up to date and subject to regular Penetration and Vulnerability tests; Bright reserve the right to view the latest set of reports to validate your Application security;
The Login/Integration button with Bright must conform to the Bright Integration section below;
Your Application/system must conform to the GDPR section below;
To integrate with BrightPay your application will need to present a button with a link to BrightID. The implementation must include the following:
The text “By clicking below you agree to share your data in line with BrightPay Terms & Privacy Policy”
The button must have the text “Login to Bright”
An example implementation is shown below
As you are now the Data Controller it is your responsibility to conform to GDPR legislation. You must put in place with the Account Holder a GDPR-compliant data processing agreement covering items such as what data you are going to hold, for how long, and who is allowed to access the data etc. Your security model around accessing/updating data or viewing retrieved data must be agreed with the Account Holder. Your agreement with the Account Holder may need to cover communication with the API not directly initiated by the Account Holder, such as on a schedule.
You will have your own additional reporting obligations directly towards your clients.
Terms must link to
Privacy Policy must link to
Under GDPR, if you suspect or are subject to a data breach, you must inform Bright within 24 hours of becoming aware of the incident. In the first instance, please contact .
