Documentation outline
The whole of the MuoCeon developer docs — purpose, audience, sections, section guides, reading paths and conventions.
This is the MuoCeon developer documentation. Every external-facing protocol, flow and convention lives here, and it is the single source of truth: when an email, a chat message or a sample code snippet disagrees with this page, this page wins.
What this documentation is
It is a contract document, not a tutorial collection. It describes only externally observable behaviour: endpoint addresses, request parameters, response structures, error codes and boundary conditions.
It deliberately does not describe internals — no table schemas, no cache key names, no internal call chains. The reason is practical: internals get refactored, and once they are published as external docs, refactoring becomes a compatibility break. All you need to know is "what I send, what the server sends back".
| It is | It is not |
|---|---|
| Stable contracts for external interfaces | Internal architecture notes |
| Verifiable steps with expected results | Vague conceptual explainers |
| Grounds for deciding what went wrong | A support ticket system |
Who it is for
| Reader | What they care about | Suggested starting point |
|---|---|---|
| External developers | Letting their app sign users in with MuoCeon | Integration guide |
| Backend developers | Validating tokens, calling protected resources, handling errors | Tokens, Error codes |
| Mobile / desktop developers | How a secret-less client obtains tokens safely | Redirect URI policy |
| Product and operations | What to prepare before integration, what review looks at | Registering a client |
| End users | What the consent page is asking, how to revoke access | FAQ |
You do not need to have read MuoCeon's source code or know its internals.
Documentation sections
The docs are organised into sections, each answering one class of question with no overlap:
| Section | Question it answers | Shape | Guide |
|---|---|---|---|
| Introduction | What does this documentation cover, where do I start | Outline, section guides, reading paths, conventions | This page |
| Integration guide | How do I integrate from scratch, how do I verify each step | Step-by-step, with examples and expected results | Integration guide overview |
| API reference | What exactly does this endpoint or field mean | Parameter tables, response samples, field constraints | API reference overview |
| FAQ | I am stuck, or a user is confused — look here first | Question → cause → fix, split by audience | FAQ overview |
The integration guide is the most complete today: the whole of third-party OAuth integration (registration, flows, permissions and security, endpoints and error codes) lives there. API reference currently provides the overview plus version and context skeletons, with field-by-field docs to follow per context. FAQ already covers the most common questions from users and developers.
Section guides
"Introduction" is not one page but four: this page gives the whole picture, the other three explain what each section contains, in what order to read it, and what is deliberately left out.
| Guide | What it covers | When to read it |
|---|---|---|
| Integration guide overview | The four groups inside the integration guide, how pages depend on each other, the three-stage order | Before deciding to integrate |
| API reference overview | How API reference differs from the integration guide, how to look up fields by version and context, how to read parameter tables | When you need exact field definitions |
| FAQ overview | The split between end-user and developer answers, how to search by symptom and error code | When you are stuck, or a user asks |
None of the three is long, but each states explicitly what does not belong in its section — knowing the boundaries is more useful than knowing the table of contents.
Reading paths
You do not need to read the docs front to back. Pick the path that matches your situation.
First integration, want to get running fast
- This page, to confirm scope;
- Third-party OAuth integration to recognise the three roles;
- Registering a client to obtain credentials;
- Quick start to run one complete flow in fifteen minutes;
- Tokens to make validation solid.
Already integrating, but something keeps failing
- The troubleshooting order in Error codes covers most cases;
- Callback failures: Redirect URI policy;
- Permission failures: Scopes and audiences.
Building for mobile or desktop
- Redirect URI policy to confirm the platform and address shape;
- Quick start to get the PKCE flow working;
- The storage guidance in Tokens — especially relevant on mobile.
Want to understand the security boundaries
Read in order: Scopes and audiences → Redirect URI policy → Authentication strength → Tokens.
Conventions
All addresses in the docs are placeholders. Replace them with your own values when integrating:
| Placeholder | Meaning |
|---|---|
{issuer} | Authorization server identifier, e.g. https://id.example.com/v1/oauth |
{origin} | The origin of {issuer}, e.g. https://id.example.com |
{consentUi} | Consent UI address, read from the metadata's authorization_endpoint |
{clientId} / {clientSecret} | Credentials obtained after registering on the developer platform |
Three general rules:
- Trust the metadata: domains, paths and supported algorithms can change per deployment. Read them from discovery rather than copying the domains in examples.
- Examples illustrate, they do not define: tokens,
subandstatein samples are fake values; the contract is defined by the parameter tables and field descriptions. - Capabilities have boundaries: the docs state clearly which capabilities are "not applicable to third parties" (token exchange, fine-grained authorization). Do not try to work around them — the server rejects them outright.
Changes and feedback
- The docs are updated alongside the interfaces; behaviour changes note their impact on the relevant page.
- If the docs disagree with actual behaviour, report it as "the docs are wrong" rather than working around it — the former gets fixed, the latter leaves a long-term hazard.
- The developer platform is not live yet; client creation currently goes through manual registration. Once live, the process and fields stay the same — see Registering a client.