What this API does:
Open Banking compliant OpenID Connect provider
This API supports OpenID Connect code and hybrid flows as per: https://openid.net/specs/openid-connect-core-1_0.html The documentation on this page is illustrative of the behaviour of the API, but should not be considered binding. Instead, the behaviour of this API is defined in the OpenBanking security profile, which inherits from the FAPI RW specification, which inherits from the OpenID Connect specification, which in turn inherits from OAuth2.0 (https://tools.ietf.org/html/rfc6749).
IMPORTANT In production this API is hosted across two endpoints as the TLS requirements for each of the calls is different. The endpoints should be used as follows:
- /authorize establishes a one-way TLS connection (acceptable for the PSU's user agent)
- /token establishes a mutually authenticated TLS connection (required to access Open Banking resources)
The production endpoints are documented in Frequently Asked Questions
Endpoint configuration
GET /oauth2/authorize
POST /oauth2/tokenProduction: https://secureapi.prod.ob.virginmoney.com/vmpsd2-psd2prod/psd2-production/oidcapi/oauth2/token
API calls
POST /oauth2/token Request Access TokensSupported Flows:
- Authorization Code (exchange code for access token)
- Client Credentials The table below indicates the required parameters for each specific grant_type options. Empty cells indicate a parameter is ignored for that specific grant type.
Scopes:
The following scopes are supported:
- openid
- accounts
- payments
- fundsconfirmations
Client authentication:
Clients must authenticate using one of the supported authentication mechanisms below:
- client_secret_basic: Authenticate using client_id and client_secret via HTTP Basic Authentication.
- client_secret_post: Post the client_id and client_secret as formData parameters.
- mtls_client_auth: Post the client_id as a formData parameter and establish a Mutually Authenticated TLS connection with the token endpoint, using a valid OpenBanking signed certificate
- client_secret_jwt: Post a JWT signed using an HMAC SHA algorithm (e.g. HS256). The HMAC is calculated using the octets of the UTF-8 representation of the client_secret issued during onboarding ( https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication Link opens in a new window ).
- private_key_jwt: Post a JWT signed using an RSASSA-PSS SHA algorithm (e.g. PS256). The signature is created using a private key that corresponds to any public key with use: 'sig', that is hosted in the in the organisation's software_jwks_endpoint ( https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication Link opens in a new window ).
| grant_type | code | client_credentials |
|---|---|---|
| client_id | required | required |
| client_secret | optional | optional |
| code | required | |
| redirect_uri | required | |
| scope | required | required |
| client_assertion | optional | optional |
| client_assertion_type | optional | optional |
| Name | Description |
|---|---|
grant_type *requiredstring(formData) | Available values : authorization_code, client_credentials |
client_idstring(formData) | Application secret, must be provided in formData or using HTTP Basic Authentication |
client_secretstring(formData) | Application client ID, can be provided in formData or using HTTP Basic Authentication |
codestring(formData) | Authorization code provided by the /oauth2/authorize endpoint |
redirect_uristring(formData) | required only if the redirect_uri parameter was included in the authorization request /oauth2/authorize; their values MUST be identical. |
scope *requiredstring(formData) | Scope being requested |
client_assertionstring(formData) | Signed assertion if using either client_secret_jwt or private_key_jwt client authentication schemes |
client_assertion_typestring(formData) | Type of client assertion if using either client_secret_jwt or private_key_jwt client authentication schemes |
Responses
Response content type: text/html
| Code | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | json document containing token, etc. { "token_type" : "bearer" , "access_token" : "string" , "expires_in" : 0 , "scope" : "string" , "id_token" : "string" , "consented_on" : "string" }
| ||||||||||||
| 400 | json document that may contain additional details about the failure | ||||||||||||
| 401 | json document that may contain additional details about the failure |
GET /oauth2/authorize Endpoint for Hybrid flow grant types | Name | Description |
|---|---|
response_type *requiredstring (string) | request an authorization code or or access token (implicit) Available values : code, code id_token |
scope *requiredstring (string) | Scope being requested |
redirect_uri *requiredstring (string) | URI where user is redirected to after authorization |
statestring(string) | This string will be echoed back to application when user is redirected |
client_id *requiredstring (string) | The client ID of the calling application |
request *requiredstring (string) | The signed request object |
noncestring(string) | A string value used to associate a Client session with an ID Token |
Responses
Response content type: text/html
| Code | Description |
|---|---|
| 200 | An HTML form for authentication or authorization of this request. |
| 302 | Redirect to the clients redirect_uri containing either an authorization code or an error in case of errors, such as the user has denied the request. For hybrid flow requests the redirection response will also contain an ID_Token. |
Models
| token_type * | stringEnum: Array [ 1 ] [ bearer ] |
| access_token * | string |
| expires_in * | integer |
| scope * | string |
| id_token | string |
| consented_on * | string |
Having trouble?
Contact our dedicated team members via our ticketing system or via our support mailbox
