To register your application, the first step is to complete the registration form.
Metro Bank is not currently accepting registrations from organisations that are not authorised for Account Information Requests (AIS) by the Financial Conduct Authority (FCA)
The registration form requires the details of the application you are registering and some important details such as your FCA registration number.
When the form is sent to Metro Bank, we will verify your FCA registration before continuing with the registration.
The first app created upon registration is the on-boarding app. On-boarding app key and secret can be found here
When the Metro Bank verification of your FCA listing is complete, the following shall be made available:
- A Metro Bank issued TLS certificate
- On-boarding app key and secret (discover these in My Apps)
Metro Bank requires that API requests are made over a connection secured with mutual TLS.
The Metro Bank issued TLS certificate should be used to establish a connection for both sandbox and production.
To verify the identity of Metro Bank, the certificate keyset to trust in your app can be found by consuming the API api.metrobankonline.co.uk/oauth/v1/.well-known/openid-configuration. Please note, you will require mutual TLS certificate to access this API endpoint.
Registering with the on-boarding app
Requests to the APIs for completion of registration require an access token.
The access token is required to obtain a SSA and to register with the SSA and also to register the app via API.
Obtaining a software statement assertion (SSA)
Using the on-boarding app key and secret, post a request to the /token resource, with client credentials grant type and a scope of manage.register. More details about token generation can be found here.
Then, with the obtained access token supplied as a bearer token in an authorisation header, post a request to the /ssa resource. More details about /ssa resource can be found here.
The SSA request must reference your FCA registration number - this should be the same as the FCA registration number supplied on the registration form.
The API response includes the newly generated SSA; a JSON Web Token (JWT).
More information about JSON Web Tokens can be found here: https://jwt.io/introduction.
- Is an electronic statement of the details you supplied on the registration form with some additional information
- To verify the identity of Metro Bank, the certificate keyset to trust in your app can be found by consuming the API api.metrobankonline.co.uk/oauth/v1/.well-known/openid-configuration. Please note, you will require mutual TLS certificate to access this API endpoint
When you receive the SSA, we recommend that you verify the signature using the Metro Bank public key.
Use one of the recommended JWT libraries listed at https://jwt.io to verify the Metro Bank signature.
The Metro Bank public key can be found in the JWKS reference by consuming the API api.metrobankonline.co.uk/oauth/v1/.well-known/openid-configuration. Please note, you will require mutual TLS certificate to access this API endpoint.
Registering via API
To complete the registration of your application and generate the key and secret for sandbox testing, the SSA must be returned to Metro Bank as the content of a new JWT that is signed with the certificate supplied to you by Metro Bank.
This new JWT forms the request payload to be posted to the /register resource.More details about /register resource can be found here.
Post the JWT containing the SSA to /register and a new app is now visible here in the developer portal. This new app grants you access to the sandbox APIs.
The SSA expires after 60 minutes. If the registration is not complete before the SSA expires then a new SSA must be requested.
Creation of the register payload JWT with SSA
The JWT payload for /register must be signed using your public/private key pair issued after completing the registration form. The public key is the Metro Bank certificate that was issued to you.
Below is an example of a decoded JWT used for registration:
Important points to note about the above example:
In the JWT header:
- alg: We support RS256 and ES256
- kid: X.509 Certificate SHA-1 Thumbprint. The thumprint of the signing certificate - this is the certificate issued to you by Metro Bank. Please ensure the thumbprint is used for the kid to enable registration to complete.
In the JWT body:
- iss: This is a mandatory field. This should be your client ID for your on-boarding app
- iat: This is a mandatory field. Time of issuance of request. (rfc7519)
- exp: This is a mandatory field. Request Expiration time. (rfc7519)
- aud: This is a mandatory field. This should be the fully qualified /register endpoint.
- grant_types: Optional, however if passed checks for both; "authorization_code" "client_credentials"
- response_types: This is a mandatory field. Check for "code id_token" or "id_token code"
- token_endpoint_auth_method: This is a mandatory field. Should be set to "private_key_jwt"
- software_id: This is a mandatory field. The value must match the software_id in the SSA
- scope: This is a optional field. If passed the scope must include "openid". Additional scopes may be requested here - these should be appropriate to the role that your registration is requesting (e.g. AISPs should submit "openid accounts")
- software_statement: This is mandatory. The SSA is included in the software_statement attribute. The SSA JWT must not be altered from the original token that you received from /ssa.
A successful registration generates a response similar to the example below:
When Metro Bank receives your SSA and verifies your signature, the on-boarding app is removed from the developer portal.
With access to the sandbox APIs you can test your application with the Metro Bank APIs before moving to the live APIs.
More information about the APIs can be found here. The Sandbox APIs are hosted at https://sandbox.metrobankonline.co.uk
I'm ready for production: Promote Me!
When you have completed the development and testing of your application with the sandbox APIs, obtaining access to the production APIs is simple:
Click on the "Promote Me" button at myapps section
Upon promotion, Metro Bank automatically creates a new production application with a key and secret that grants access to our live APIs.
This new application is now visible here in the developer portal. The Production APIs are hosted at https://api.metrobankonline.co.uk