---
updatedAt: 2026-03-12T18:05:27.000Z
agentTools:
projectIndex: https://docs.moneyhubenterprise.com/llms.txt
---
# Authentication
We provide an OpenID Connect compliant interface that should work well with any OpenID Connect certified relying party software.
This document will provide a high level overview, but we recommend that users familiarise themselves with the following specs:
* [OpenID Connect Core](http://openid.net/specs/openid-connect-core-1_0.html)
* [Financial Grade API Read Only Profile](https://bitbucket.org/openid/fapi/src/master/Financial_API_WD_001.md)
* [Financial Grade API Read/Write Profile](https://bitbucket.org/openid/fapi/src/master/Financial_API_WD_002.md)
Base URL:
* [https://identity.moneyhub.co.uk](https://identity.moneyhub.co.uk/)
## Discovery
`https://identity.moneyhub.co.uk/oidc/.well-known/openid-configuration`
[OpenID Connect Discovery Spec](http://openid.net/specs/openid-connect-discovery-1_0.html)
Our discovery document is available [here](https://identity.moneyhub.co.uk/oidc/.well-known/openid-configuration). It will contain our up-to-date machine readable configuration and for example will list our:
* token endpoint
* authorisation endpoint
* jwks endpoint
* scopes that we support
* claims that we support
* the cryptographic algorithms we support
* the response types we support
Examples of discovery metadata from other providers are:
* [Google](https://accounts.google.com/.well-known/openid-configuration)
* [Microsoft](https://login.windows.net/contoso.onmicrosoft.com/.well-known/openid-configuration)
## Response Types
Our discovery doc will list the response types that we support. Currently these are: `code`, `code id_token` and `id_token`.
`code` is fairly straight forward and is the standard OAuth 2 authorisation code flow.
`code id_token` is one of the variants of the hybrid flow and isn’t always understood. At a basic level it means that we will send an `id_token` along with the authorisation code when we redirect the user back to your `redirect_uri`. This id\_token doesn’t contain any identity information, but is rather a detached signature which cryptographically binds the authorization\_code we send back with the nonce and the state that you sent to us. It prevents a certain class of code interception attacks and we encourage implementers to use it rather than the basic authorisation code flow.
> 🚧 Response type configuration
>
> When using response\_type "code id\_token", the redirect URL should be https, rather than http, and grant types configured for the API Client should include "implicit". This is required for production use.
>
> Alternatively, during development, use the "code" response type, without the "implicit" grant type, and you can use http redirect URLs.
## Token Endpoint
`https://identity.moneyhub.co.uk/oidc/token`
To obtain an Access Token, an ID Token, and optionally a Refresh Token, the RP (Client) sends a Token Request to the Token Endpoint to obtain a Token Response when using the Authorisation Code Flow.
[OpenID Connect Token Spec](http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint)
We support the following grant types:
* `authorization_code`
* `client_credentials`
* `refresh_token`
### Authenticating on the Token Endpoint
Depending on the configured token endpoint method, the authentication sent to the token end point will differ. If you are using a client with `client_secret_basic` (which is not a recommended approach) then an `Authorisation` header will be sent with a value of `Basic base_64_env(${client_id}:${client_secret})`.
If your client has a token endpoint authentication method of `private_key_jwt` you will also need a JWT when getting a token. The JWT will have the following properties in the payload:
* `iss` - your client id
* `sub` - your client id
* `jti` - A unique identifier for the token, which can be used to prevent reuse
* `aud` - our token endpoint, i.e. `https://identity.moneyhub.co.uk/oidc/token`
* `iat` - the time at which the token was issued
* `exp` - the time at which the token will expire
The JWT is put in the token endpoint body in the property `client_assertion`. The `client_assertion_type` will need to be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
### Example JWT for client assertion
`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRxVk1laV9XdUtqZW5HWlJUbnJpeUxXRnZuS2tzTjNvLWFuWXBqS0JEbVUifQ.eyJqdGkiOiJmRnVjb0JpZTc2MGhJcXA3Vn5CeGQiLCJpc3MiOiI5NzlhYmRhYi1mZDY0LTQyZTYtYWJkMi1lZTc0NTQyZjM0OTMiLCJpYXQiOjE2MjI4MTIzNzUsImV4cCI6MTYyMjgxMjk3NSwiYXVkIjoiaHR0cHM6Ly9pZGVudGl0eS5tb25leWh1Yi5jby51ay9vaWRjL3Rva2VuIiwic3ViIjoiOTc5YWJkYWItZmQ2NC00MmU2LWFiZDItZWU3NDU0MmYzNDkzIn0.Q0CFDaGNAv5qCnH_VLN0Hw62A0NvXqTdwKazaAoV7Vo`
```json Unencoded JWT payload for client assertion
{
"jti": "fFucoBie760hIqp7V~Bxd",
"iss": "979abdab-fd64-42e6-abd2-ee74542f3493",
"iat": 1622812375,
"exp": 1622812975,
"aud": "https://identity.moneyhub.co.uk/oidc/token",
"sub": "979abdab-fd64-42e6-abd2-ee74542f3493"
}
```
### Notes
* You will need to provide a unique token identifier and set it to the jti property for all JWTs.
* An issued at and expiry time will be required in the JWTs.
* We would recommend using our API Client Library to generate these auth URLs and token requests if you are developing in JavaScript, or to find an OpenID Connect library for your chosen language that supports request objects.
### JWT requests
More information about JWT requests is available [here](http://openid.net/specs/openid-connect-core-1_0.html#JWTRequests)
### Client credentials
For a detailed look at the client credentials grant, please look at [this document](client-credentials-token).
### Authorisation Code
For a detailed look at the authorisation code grant, please look at [this document](https://docs.moneyhubenterprise.com/docs/completing-a-connection).
### Refresh Token
The `refresh_token` grant type is implemented exactly as according to the specs in [RFC6749](https://tools.ietf.org/html/rfc6749) and [OIDC](http://openid.net/specs/openid-connect-core-1_0.html).
## JWKS Endpoints & Asymmetric Signatures
The [JSON Web Key Set (JWKS)](https://docs.moneyhubenterprise.com/docs/api-clients#jwks-key-set) endpoint is a read-only endpoint that returns your public key set in the JWKS format. This contains the signing key(s) that we will use to validate signatures from the tokens issued using your credentials. More information on this endpoint is available in the [OIDC specs](https://openid.net/specs/openid-connect-discovery-1_0.html#JWK)
We use jwks endpoints to support the [rotation of signing keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)
As part of registering your client software with us, we will ask you for your own jwks endpoint.
If you don’t yet have one, we strongly encourage you to implement one. JWKS endpoints provide a neat method to achieve key rotation without any interruption to service or any need for bilateral communication.
They enable you to manage your keys in which ever manner you see fit and removes the need for the `client_secret`.
The endpoint should be publicly accessible and should serve an array of public keys in JSON format like the example below:
```json JWKS set
{
"keys": [
{
"kty": "RSA",
"e": "AQAB",
"use": "sig",
"kid": "NTAxZmMxNDMyZDg3MTU1ZGM0MzEzODJhZWI4NDNlZDU1OGFkNjFiMQ",
"alg": "RS256",
"n": "luZFdW1ynitztkWLC6xKegbRWxky-5P0p4ShYEOkHs30QI2VCuR6Qo4Bz5rTgLBrky03W1GAVrZxuvKRGj9V9-PmjdGtau4CTXu9pLLcqnruaczoSdvBYA3lS9a7zgFU0-s6kMl2EhB-rk7gXluEep7lIOenzfl2f6IoTKa2fVgVd3YKiSGsyL4tztS70vmmX121qm0sTJdKWP4HxXyqK9neolXI9fYyHOYILVNZ69z_73OOVhkh_mvTmWZLM7GM6sApmyLX6OXUp8z0pkY-vT_9-zRxxQs7GurC4_C1nK3rI_0ySUgGEafO1atNjYmlFN-M3tZX6nEcA6g94IavyQ"
}
]
}
```
| Property value | description |
| :------------- | :----------------------------------------------------------------------------------------------------------------------- |
| kty | The public key type. |
| e | The exponent value of the public key. |
| use | Implies how the key is being used. The value sig represents signature. |
| kid | The thumbprint of the certificate. This value is used to identify the key that needs to be used to verify the signature. |
| alg | The algorithm used to secure the JSON Web Signature. |
| n | The modulus value of the public key. |
## Errors
Many of the errors returned are in accordance with the OpenId Connect specification.
### Authorisation error response
The error codes returned from [https://identity.moneyhub.co.uk/oidc/auth](https://docs.moneyhubenterprise.com/reference/get_oidc-auth) will match those in the OpenId spec. Please [see here](https://openid.net/specs/openid-connect-core-1_0.html#AuthError) for a list of those errors.\
OpenId Connect adds to the list of errors in the Oauth 2.0 spec. Please [see here](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1) for a list of the Oauth 2.0 errors. For convenience we've also listed those errors here:
* `invalid_request` - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
* `unauthorized_client` - The client is not authorized to request an authorisation code using this method.
* `access_denied` - The resource owner or authorisation server denied the request
* `unsupported_response_type` - The authorisation server does not support obtaining an authorisation code using this method.
* `invalid_scope` - The requested scope is invalid, unknown or malformed.
* `server_error` - There was an unexpected error
* `temporarily_unavailable` - The authorisation server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
* `invalid_request_uri` - The request\_uri in the Authorisation Request returns an error or contains invalid data.
* `invalid_request_object` - The request parameter contains an invalid Request Object.
* `access_denied` - Returned on redirect when user cancels the flow whilst in providers authorisation screen.
### Token error response
The error codes returned from the [https://identity.moneyhub.co.uk/oidc/token](https://docs.moneyhubenterprise.com/reference/post_oidc-token) endpoint will match those in the Oauth 2.0 spec. Please [see here](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) for a list of Oauth errors that can be returned. For convenience please also see that list below.
* `invalid_request` - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
* `invalid_client` - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
* `invalid_grant` - The provided authorisation grant (e.g., authorisation code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorisation request, or was issued to another client.
* `unauthorized_client` - The authenticated client is not authorized to use this authorisation grant type.
* `unsupported_grant_type` - The authorisation grant type is not supported by the authorisation server.
* `invalid_scope` - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
For more information about the benefits of this approach or advice on implementing, please contact us.