aknAPI
| URL | https://api.akn.me.uk |
| Description | HTTP API for akn ID sessions, federated sign-in, and the data served to akn's own sites |
| Access | Public endpoints are open. The rest require an approved akn ID account, a project grant, an API key, or a registered OIDC client |
| Pricing | Free |
Overview
aknAPI allows a developer to verify an akn ID sign-in, open and refresh a session, and read the status, role and project grants attached to the person behind it. Authorisation controls are held by akn ID: every gated endpoint checks account status first, then the project grant the endpoint requires.
The same service acts as an OpenID Connect provider for relying parties, bridges sign-in methods that cannot be used directly, and serves the notification, calendar, status and location data behind akn's own sites.
Capabilities
| Capability | Availability |
|---|---|
| Verify a sign-in and open a session | Any caller holding a valid ID token |
| Read the signed-in person's status, role and project grants | Session cookie or bearer ID token |
| Sign in with a code sent to an email address | Public |
| Request an account | Public |
| Sign in through a bridged provider | Public |
| Act as an OpenID Connect provider, authorisation code flow | Registered relying parties |
| Supply authorisation claims to an upstream identity provider | Signed callers only |
| Administer people, grants and linked identities | Admin role |
| Submit a notification | API key holders |
| Read notifications and the owner's calendar | startpage project grant |
| Read location and visitor summaries | Public |
| Manage status incidents and monitored URLs | Admin role, or status project grant |
| Refresh tokens on the OIDC provider | Not available |
| Dynamic client registration | Not available |
| Single logout across relying parties | Not available |
| Pagination on any list endpoint | Not available |
| Webhooks or streaming responses | Not available |
| Deleting a person | Not available |
| Rate limiting outside the email code endpoints | Not available |
Endpoint groups
| Group | Path prefix | Purpose |
|---|---|---|
| Sessions and sign-in | /auth | Verify a sign-in, hold a session, obtain a credential |
| People administration | /auth/people, /auth/sync | Manage people, grants and linked identities |
| OpenID Connect | /auth/oidc, /auth/zitadel | Federate akn ID to a relying party or an upstream provider |
| Notifications, calendar and status | /startpage, /calendar, /status | Data for the startpage and status sites |
| Location | /location | Location summaries and visitor records |
Service check
GET / requires no credential and answers with a fixed body.
{ "ok": true, "service": "akn-api" }
Conventions
| Property | Detail |
|---|---|
| Request bodies | JSON. The token endpoint also accepts form encoding |
| Response bodies | JSON, except bridge errors, which are HTML pages |
| Timestamps | ISO 8601 in UTC, unless stated otherwise on the endpoint |
| Versioning | None. Paths are unversioned and change in place |
| Idempotency | Not offered. No request identifier is honoured |
Next steps
- Authentication covers credentials, sessions and CORS.
- Sessions and sign-in covers the session and credential endpoints.
- Errors covers the error shapes a caller must handle.
- Diagnostics lists integration conditions and resolutions.
Related products
- aknID, sign-in provider for sessions this API issues