---
updatedAt: 2026-06-08T07:49:17.000Z
agentTools:
  projectIndex: https://docs.enrichment-engine.moneyhubenterprise.com/llms.txt
---

# Retrieve an access token

Obtain a client credentials access token using `private_key_jwt` authentication.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "description": "Documentation for authenticating to the Categorisation & Enrichment Engine API.",
    "title": "Moneyhub Authentication API — OAuth 2.0 / OpenID Connect",
    "version": "2.0.0"
  },
  "externalDocs": {
    "description": "Authentication guide",
    "url": "https://docs.enrichment-engine.moneyhubenterprise.com/docs/api-authn-authz"
  },
  "paths": {
    "/oidc/token": {
      "post": {
        "summary": "Retrieve an access token",
        "description": "Obtain a **client credentials** access token using `private_key_jwt` authentication.\n\n## Prerequisites\n\nYour API client must be configured in the Admin Portal with:\n\n- `token_endpoint_auth_method` set to **private_key_jwt**\n- A **JWKS** key set or **jwks_uri** registered so Moneyhub can verify your assertion signatures\n\n## Client authentication (private_key_jwt)\n\nAuthenticate by signing a JWT with your registered private key and sending it in the form body:\n\n| Field | Value |\n|-------|-------|\n| `client_id` | Your API client id |\n| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |\n| `client_assertion` | A signed JWT (see claims below) |\n\n### Required JWT claims (`client_assertion` payload)\n\n| Claim | Description |\n|-------|-------------|\n| `iss` | Your **client id** (issuer) |\n| `sub` | Your **client id** (subject) |\n| `aud` | Token endpoint URL, e.g. `https://identity.moneyhub.co.uk/oidc/token` (must match the request URL; also accepted: issuer identifier) |\n| `jti` | A **unique** identifier for this JWT (must not be reused) |\n| `iat` | Issued-at time (Unix seconds) |\n| `exp` | Expiry time (Unix seconds); must be present |\n\nSign the JWT with a private key whose public key is in your registered JWKS. Supported signing algorithms include **RS256**, **RS384**, **RS512**, **PS256**, **PS384**, **PS512**, **ES256**, **ES384**, and **ES512**.\n\nUse the [OIDC discovery document](https://identity.moneyhub.co.uk/oidc/.well-known/openid-configuration) for canonical endpoint URLs.",
        "externalDocs": {
          "description": "Moneyhub authentication guide",
          "url": "https://docs.enrichment-engine.moneyhubenterprise.com/docs/client-credentials"
        },
        "security": [
          {
            "private_key_jwt": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type",
                  "scope",
                  "client_id",
                  "client_assertion",
                  "client_assertion_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "description": "Must be `client_credentials`.",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "scope": {
                    "type": "string",
                    "description": "Space-separated scopes required for your integration. CaaS scopes (caas:*)"
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Your API client id. Must match `iss` and `sub` in `client_assertion`."
                  },
                  "client_assertion": {
                    "type": "string",
                    "description": "Signed JWT used to authenticate the client at the token endpoint (private_key_jwt)."
                  },
                  "client_assertion_type": {
                    "type": "string",
                    "description": "OAuth client assertion type.",
                    "enum": [
                      "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A successful token retrieval response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Token"
                }
              }
            }
          },
          "400": {
            "description": "OAuth 2.0 error response (e.g. `invalid_client`, `invalid_grant`, `invalid_scope`, `unsupported_grant_type`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "OAuth 2.0 error code"
                    },
                    "error_description": {
                      "type": "string",
                      "description": "Human-readable error description"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Unsuccessful response — invalid scopes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "tags": [
          "auth"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "private_key_jwt": {
        "type": "oauth2",
        "description": "The only supported client authentication method for this API. Sign a JWT with your registered private key and send it as `client_assertion` in the token request body (with `client_assertion_type` and `client_id`).",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oidc/token",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "description": "The error code",
            "type": "string"
          },
          "message": {
            "description": "The error message",
            "type": "string"
          },
          "correlationId": {
            "description": "Id that identifies the request and can be used to ask for more details related to the error",
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "Token": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "access_token": {
            "description": "Access Token",
            "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRxVk1laV9XdUtqZW5HWlJUbnJpeUxXRnZuS2tzTjNvLWFuWXBqS0JEbVUifQ",
            "type": "string"
          },
          "expires_in": {
            "description": "Token Expiry",
            "example": 1616090946,
            "type": "integer"
          },
          "token_type": {
            "description": "Type of token granted",
            "example": "Bearer",
            "type": "string"
          },
          "scope": {
            "description": "The granted scopes",
            "example": "id:1ffe704d39629a929c8e293880fb449a openid",
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "expires_in",
          "token_type"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://identity.moneyhub.co.uk"
    }
  ]
}
```