# Smart Pension

> Smart Pension is a UK defined contribution workplace pension master trust operated by Smart Pension Limited (Smart Group), managing pensions for millions of UK savers on behalf of over 90,000 employers. Its API surface is the Keystone API — the same public REST API that powers Smart's own employer, employee and adviser portals — published by Keystone, Smart's proprietary savings administration platform.

Generated by API Evangelist on 2026-08-05. Smart Pension does not publish an llms.txt of its own; this file was generated from the provider's published OpenAPI and developer documentation. It is a third-party profile, not a Smart Pension document.

Read this first: the API reflects the underlying database, not the pensions domain. An **employer is a `company`**, a **scheme member is an `employee`**, and the employer's administrator is a **`customer`**. An **adviser** (accountant, IFA or payroll bureau) has a one-to-many relationship with companies.

## APIs

- [Keystone API](https://developers.autoenrolment.co.uk/smart): REST API for companies (employers), employees (members), contributions, auto-enrolment assessment, postponements, opt-ins/opt-outs, valuations, funds and fund splits, bank details, advisers, PAPDIS/SSIF imports and batch requests. 271 paths, 383 operations, 222 schemas. Production base URL `https://api.autoenrolment.co.uk`.

## Specs

- [OpenAPI 3.0.3 (YAML)](openapi/smart-pension-keystone-openapi.yml): the full Keystone API contract.
- [OpenAPI 3.0.3 (JSON, as harvested)](openapi/_original/smart-pension-keystone-openapi.json): verbatim export from the provider's Stoplight project.
- [API Evangelist Overlay](overlays/smart-pension-keystone-overlay.yaml): adds an operationId to all 383 operations and declares the 150 tags. **The published spec declares neither**, so no generator, workflow or agent tool can address an operation by name without this.

## Authentication

- [Authentication profile](authentication/smart-pension-authentication.yml)
- [OAuth scopes](scopes/smart-pension-scopes.yml)
- OAuth 2.0 only. Authorization code (scopes `user` / `customer` / `employee`) for apps acting for a person; client credentials with ~33 fine-grained `read:*` scopes for machine-to-machine partners. A `read` scope also permits writes.
- Client-credentials access tokens expire after **10 minutes**.
- Register a partner app per environment: [sandbox](https://partner.sandbox.autoenrolment.co.uk/partners/sign-up), [production](https://partner.autoenrolment.co.uk/partners/sign-up). Free to connect — but requested scopes must be manually enabled on your application by Smart (api@smartpension.co.uk) before calls succeed.
- JWT signing keys: `https://api.autoenrolment.co.uk/.well-known/jwks` (RFC 7517, anonymous). There is no OIDC discovery document pointing at it.

## Environments

- Production — `https://api.autoenrolment.co.uk`
- Sandbox — `https://api.sandbox.autoenrolment.co.uk` (data persists; third-party services run against their own sandboxes)
- Development — `https://api.dev.autoenrolment.co.uk` (data purged frequently)
- [Sandbox detail](sandbox/smart-pension-sandbox.yml)

## Conventions

- [API conventions](conventions/smart-pension-conventions.yml)
- Pagination: `limit` (default 50, max 100) + `offset`, with a `links` envelope carrying self/next/prev/first/last. Documented as unstable if records change while paging.
- Query shaping: `fields[]` (sparse fields), `include[]` (embed related objects), `filter[field]=value`, `sort` + `direction`.
- Writes take **bracketed query parameters** (`contribution[gross_qualifying_earnings]=1000.00`), not a JSON body.
- Batch: `POST /batch`, up to 50 operations, any endpoint.
- Versioning: integer, current **v12**, selected via `?version=N` or `Accept: application/vnd.autoenrolment.vN+json`. Unspecified means latest.
- Dates: `YYYY-MM-DD`. Malformed dates are coerced to null rather than rejected — normalise before sending.

## Things an agent must know before writing

- **There is no idempotency key.** No `Idempotency-Key` header, no replay window, no safe-retry contract. A retried contribution POST can create a duplicate pension payment. Read back before retrying and dedupe on the payroll `external_id` you control.
- **There are no webhooks and no event stream.** Change detection is polling — re-read member state before each pay run.
- **Errors are not RFC 9457.** Envelope is `code` / `title` / `detail` / `source`, arriving either as a bare object or as an array under `errors`. 500 responses return **HTML**, not JSON.
- **Rate limits** are per endpoint: 500 req/min default; 80 req/min on employee list and create; 250 req/min on contribution create. No RateLimit or Retry-After headers are published — a 429 is the only signal.

## Artifacts

- [Error catalog](errors/smart-pension-problem-types.yml)
- [Rate limits](rate-limits/smart-pension-rate-limits.yml)
- [Lifecycle and versioning](lifecycle/smart-pension-lifecycle.yml)
- [Changelog (per-version deltas)](changelog/smart-pension-changelog.yml)
- [Conformance](conformance/smart-pension-conformance.yml)
- [Data model](data-model/smart-pension-data-model.yml)
- [In-spec response examples](examples/smart-pension-keystone-examples.yml)
- [Agentic access profile](agentic-access/smart-pension-agentic-access.yml)
- [Well-known documents](well-known/smart-pension-well-known.yml)
- [Domain security](security/smart-pension-domain-security.yml)
- [Trust center](security/smart-pension-trust-center.yml)
- [Vulnerability disclosure](security/smart-pension-vulnerability-disclosure.yml)
- [Packages / SDKs](packages/smart-pension-packages.yml) — none published
- [Candidate MCP tools](mcp/smart-pension-mcp.yml) — derived, not deployed by Smart

## Agent Skills

- [Submit payroll contributions](skills/smart-pension-submit-payroll-contributions.md)
- [Import a PAPDIS file](skills/smart-pension-import-papdis-file.md)
- [Read a member's pension value](skills/smart-pension-read-member-pension-value.md)

## Docs

- [Developer portal](https://developers.autoenrolment.co.uk/smart)
- [Introduction](https://developers.autoenrolment.co.uk/smart/451fbda1e0bde-introduction)
- [Getting Started](https://developers.autoenrolment.co.uk/smart/7756f9f9959a5-getting-started)
- [OAuth](https://developers.autoenrolment.co.uk/smart/8746c0c6c82b7-o-auth)
- [Using the API](https://developers.autoenrolment.co.uk/smart/28783c05ecb6a-using-the-api)
- [Parameters](https://developers.autoenrolment.co.uk/smart/6810f928c15a0-parameters)
- [Flows](https://developers.autoenrolment.co.uk/smart/ecabd5980520c-flows)
- [Versions](https://developers.autoenrolment.co.uk/smart/42d8d78e1463a-versions)
- [Using Client Credentials](https://developers.autoenrolment.co.uk/smart/yd0a98nlh9e6c-using-client-credentials)
- [API integrations support](https://www.smartpension.co.uk/support/en/collections/2223979-api-integrations)
- [Payroll integration and partner list](https://www.smartpension.co.uk/payroll-integration)

## Company

- [Smart Pension](https://www.smartpension.co.uk/)
- [Smart Group](https://www.smart.co/)
- [Keystone by Smart](https://www.keystonebysmart.com/)
- [News and insights](https://www.smartpension.co.uk/news-and-insights)
- [Charges](https://www.smartpension.co.uk/charges)
- [Trust center](https://trust.smart.co/) — ISO 27001:2022, SOC 2 Type 2
- [Responsible disclosure policy](https://www.smart.co/footer/responsible-disclosure-program-policy) — bug bounty via Intigriti
- [Terms of use](https://www.smartpension.co.uk/legal-compliance-pages/terms-of-use)
- [Privacy notice](https://www.smartpension.co.uk/legal-compliance-pages/privacy-notice)
- [GitHub](https://github.com/smartpension)

## Not published

There is no status page, no SLA, no deprecation policy or Sunset header support, no security.txt, no OIDC discovery, no api-catalog, no agent card, no MCP server, no client SDKs, no CLI, no embeddable components, no AsyncAPI, no webhooks, and no public dated changelog or RSS feed — release announcements go only to an email newsletter.