# govuk-one-login/authentication-api architecture

> Architecture diagram of the GitHub repository govuk-one-login/authentication-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govuk-one-login/authentication-api
- Repository: https://github.com/govuk-one-login/authentication-api

## Overview

This repository implements backend authentication and orchestration for GOV.UK One Login. Its broad user-facing surface includes frontend authentication journeys, token and user-info endpoints, account management, passkeys/account data, delivery callbacks and audit events. A typical journey enters the frontend API and uses shared session, code and MFA services before producing authentication results; separate branches manage accounts and credentials. Most implementation files were not sampled, so runtime links beyond the explicitly documented frontend integrations are shown as unverified dashed edges.

Main entry points: [`frontend-api/src/main/java/uk/gov/di/authentication/frontendapi`](https://github.com/govuk-one-login/authentication-api/tree/main/frontend-api/src/main/java/uk/gov/di/authentication/frontendapi) (Frontend API), [`account-management-api/src/main/java/uk/gov/di/accountmanagement`](https://github.com/govuk-one-login/authentication-api/tree/main/account-management-api/src/main/java/uk/gov/di/accountmanagement) (Account management), [`auth-external-api/src/main/java/uk/gov/di/authentication/external`](https://github.com/govuk-one-login/authentication-api/tree/main/auth-external-api/src/main/java/uk/gov/di/authentication/external) (External API), [`account-data-api/src/main/java/uk/gov/di/authentication/accountdata`](https://github.com/govuk-one-login/authentication-api/tree/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata) (Account data API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication journeys"]
  node_frontend["Frontend API"]
end

subgraph group_account["Account services"]
  node_accountmgmt["Account management"]
  node_accountdelete["Account deletion"]
end

subgraph group_credential["Credential data"]
  node_accountdata["Account data API"]
  node_passkeys["Passkey operations"]
  node_dynamopasskeys[("Passkey storage")]
end

subgraph group_integration["External interfaces"]
  node_external["External API"]
  node_tokens["Token service<br/>[TokenService.java]"]
  node_userinfo["User info"]
  node_receipts["Delivery receipts"]
end

subgraph group_shared["Shared runtime"]
  node_session["Auth sessions"]
  node_codes["Code storage"]
  node_mfa["MFA methods"]
  node_audit["Audit events"]
  node_sharedmodels["Identity models<br/>[UserProfile.java]"]
  node_config["Runtime configuration"]
end

node_user(("User or client"))
node_ticf["TICF CRI"]
node_interventions["Account interventions"]
node_ipv["IPV service"]

node_user -.->|"starts journey"| node_frontend
node_frontend -.->|"uses sessions"| node_session
node_frontend -.->|"uses codes"| node_codes
node_frontend -.->|"manages MFA"| node_mfa
node_frontend -.->|"requests service"| node_ticf
node_frontend -.->|"requests service"| node_interventions
node_frontend -.->|"requests service"| node_ipv
node_external -.->|"handles tokens"| node_tokens
node_external -.->|"serves user info"| node_userinfo
node_accountmgmt -.->|"deletes accounts"| node_accountdelete
node_accountdata -.->|"manages passkeys"| node_passkeys
node_passkeys -.->|"stores passkeys"| node_dynamopasskeys
node_accountmgmt -.->|"proxies passkeys"| node_accountdata
node_frontend -.->|"records events"| node_audit
node_accountmgmt -.->|"records events"| node_audit
node_receipts -.->|"receives callback"| node_user
node_session -.->|"stores session data"| node_sharedmodels
node_frontend -.->|"uses identity data"| node_sharedmodels
node_config -.->|"configures runtime"| node_frontend

click node_frontend "https://github.com/govuk-one-login/authentication-api/tree/main/frontend-api/src/main/java/uk/gov/di/authentication/frontendapi"
click node_session "https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/AuthSessionService.java"
click node_codes "https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/CodeStorageService.java"
click node_mfa "https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/mfa/MFAMethodsService.java"
click node_external "https://github.com/govuk-one-login/authentication-api/tree/main/auth-external-api/src/main/java/uk/gov/di/authentication/external"
click node_tokens "https://github.com/govuk-one-login/authentication-api/blob/main/auth-external-api/src/main/java/uk/gov/di/authentication/external/services/TokenService.java"
click node_userinfo "https://github.com/govuk-one-login/authentication-api/blob/main/auth-external-api/src/main/java/uk/gov/di/authentication/external/services/UserInfoService.java"
click node_accountmgmt "https://github.com/govuk-one-login/authentication-api/tree/main/account-management-api/src/main/java/uk/gov/di/accountmanagement"
click node_accountdelete "https://github.com/govuk-one-login/authentication-api/blob/main/account-management-api/src/main/java/uk/gov/di/accountmanagement/services/AccountDeletionService.java"
click node_accountdata "https://github.com/govuk-one-login/authentication-api/tree/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata"
click node_passkeys "https://github.com/govuk-one-login/authentication-api/blob/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/PasskeysService.java"
click node_dynamopasskeys "https://github.com/govuk-one-login/authentication-api/blob/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/DynamoPasskeyService.java"
click node_audit "https://github.com/govuk-one-login/authentication-api/blob/main/audit-events/src/main/java/uk/gov/di/authentication/auditevents/services/StructuredAuditService.java"
click node_receipts "https://github.com/govuk-one-login/authentication-api/blob/main/delivery-receipts-api/src/main/java/uk/gov/di/authentication/deliveryreceiptsapi/lambda/NotifyCallbackHandler.java"
click node_sharedmodels "https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/entity/UserProfile.java"
click node_config "https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/ConfigurationService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_user toneBlue
class node_accountmgmt,node_accountdelete toneAmber
class node_accountdata,node_passkeys,node_dynamopasskeys toneMint
class node_external,node_tokens,node_userinfo,node_receipts toneRose
class node_session,node_codes,node_mfa,node_audit,node_sharedmodels,node_config,node_ticf,node_interventions,node_ipv toneIndigo
```

## Components

### Authentication journeys

- [Frontend API](https://github.com/govuk-one-login/authentication-api/tree/main/frontend-api/src/main/java/uk/gov/di/authentication/frontendapi): `frontend-api/src/main/java/uk/gov/di/authentication/frontendapi`

### Account services

- [Account management](https://github.com/govuk-one-login/authentication-api/tree/main/account-management-api/src/main/java/uk/gov/di/accountmanagement): `account-management-api/src/main/java/uk/gov/di/accountmanagement`
- [Account deletion](https://github.com/govuk-one-login/authentication-api/blob/main/account-management-api/src/main/java/uk/gov/di/accountmanagement/services/AccountDeletionService.java): `account-management-api/src/main/java/uk/gov/di/accountmanagement/services/AccountDeletionService.java`

### Credential data

- [Account data API](https://github.com/govuk-one-login/authentication-api/tree/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata): `account-data-api/src/main/java/uk/gov/di/authentication/accountdata`
- [Passkey operations](https://github.com/govuk-one-login/authentication-api/blob/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/PasskeysService.java): `account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/PasskeysService.java`
- [Passkey storage](https://github.com/govuk-one-login/authentication-api/blob/main/account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/DynamoPasskeyService.java): `account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/DynamoPasskeyService.java`

### External interfaces

- [External API](https://github.com/govuk-one-login/authentication-api/tree/main/auth-external-api/src/main/java/uk/gov/di/authentication/external): `auth-external-api/src/main/java/uk/gov/di/authentication/external`
- [Token service](https://github.com/govuk-one-login/authentication-api/blob/main/auth-external-api/src/main/java/uk/gov/di/authentication/external/services/TokenService.java): `auth-external-api/src/main/java/uk/gov/di/authentication/external/services/TokenService.java`
- [User info](https://github.com/govuk-one-login/authentication-api/blob/main/auth-external-api/src/main/java/uk/gov/di/authentication/external/services/UserInfoService.java): `auth-external-api/src/main/java/uk/gov/di/authentication/external/services/UserInfoService.java`
- [Delivery receipts](https://github.com/govuk-one-login/authentication-api/blob/main/delivery-receipts-api/src/main/java/uk/gov/di/authentication/deliveryreceiptsapi/lambda/NotifyCallbackHandler.java): `delivery-receipts-api/src/main/java/uk/gov/di/authentication/deliveryreceiptsapi/lambda/NotifyCallbackHandler.java`

### Shared runtime

- [Auth sessions](https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/AuthSessionService.java): `shared/src/main/java/uk/gov/di/authentication/shared/services/AuthSessionService.java`
- [Code storage](https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/CodeStorageService.java): `shared/src/main/java/uk/gov/di/authentication/shared/services/CodeStorageService.java`
- [MFA methods](https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/mfa/MFAMethodsService.java): `shared/src/main/java/uk/gov/di/authentication/shared/services/mfa/MFAMethodsService.java`
- [Audit events](https://github.com/govuk-one-login/authentication-api/blob/main/audit-events/src/main/java/uk/gov/di/authentication/auditevents/services/StructuredAuditService.java): `audit-events/src/main/java/uk/gov/di/authentication/auditevents/services/StructuredAuditService.java`
- [Identity models](https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/entity/UserProfile.java): `shared/src/main/java/uk/gov/di/authentication/shared/entity/UserProfile.java`
- [Runtime configuration](https://github.com/govuk-one-login/authentication-api/blob/main/shared/src/main/java/uk/gov/di/authentication/shared/services/ConfigurationService.java): `shared/src/main/java/uk/gov/di/authentication/shared/services/ConfigurationService.java`

### Other components

- **User or client**
- **TICF CRI**
- **Account interventions**
- **IPV service**

## Connections

- User or client → Frontend API: starts journey
- Frontend API → Auth sessions: uses sessions
- Frontend API → Code storage: uses codes
- Frontend API → MFA methods: manages MFA
- Frontend API → TICF CRI: requests service (evidence: `README.md`)
- Frontend API → Account interventions: requests service (evidence: `README.md`)
- Frontend API → IPV service: requests service (evidence: `README.md`)
- External API → Token service: handles tokens
- External API → User info: serves user info (evidence: `auth-external-api/src/main/java/uk/gov/di/authentication/external/services/UserInfoService.java`)
- Account management → Account deletion: deletes accounts (evidence: `account-management-api/src/main/java/uk/gov/di/accountmanagement/services/AccountDeletionService.java`)
- Account data API → Passkey operations: manages passkeys (evidence: `account-data-api/src/main/java/uk/gov/di/authentication/accountdata/lambda/PasskeysRetrieveHandler.java`)
- Passkey operations → Passkey storage: stores passkeys (evidence: `account-data-api/src/main/java/uk/gov/di/authentication/accountdata/services/PasskeysService.java`)
- Account management → Account data API: proxies passkeys
- Frontend API → Audit events: records events (evidence: `frontend-api/src/main/java/uk/gov/di/authentication/frontendapi/services/webauthn/PasskeyAssertionService.java`)
- Account management → Audit events: records events (evidence: `account-management-api/src/main/java/uk/gov/di/accountmanagement/services/AccountDeletionService.java`)
- Delivery receipts → User or client: receives callback
- Auth sessions → Identity models: stores session data
- Frontend API → Identity models: uses identity data
- Runtime configuration → Frontend API: configures runtime (evidence: `frontend-api/src/main/java/uk/gov/di/authentication/frontendapi/services/AMCService.java`)