| title | Quickstart |
|---|---|
| description | Start building awesome documentation in minutes |
| icon | rocket |
Welcome. This page walks you from first contact through your first successful API call, then explains how the API decides what each request is allowed to see and do.
The story is told from the perspective of a fictional customer — Acme Corp — onboarding to our platform. Every step mirrors the real flow.
You authenticate to our API using your own OAuth 2.0 / OpenID Connect identity provider — typically Microsoft Entra, Okta, Auth0, or Google Workspace. You mint a JWT access token against your IdP, send it as a Bearer token, and we validate it: signature, issuer, audience, expiry. We then resolve the organisation identity linked to your IdP tenant in our system, attach it to the request, and pass it to a layered authorisation pipeline that decides what the request can read, write, and see.
You never share a secret with us. We never issue you a credential. Your IdP is the source of truth.
Acme's data team emails support:
"We'd like programmatic access to our records on your platform."
Support replies with a short checklist:
Authenticate using your own corporate identity provider. Send us:
- Your IdP type (Microsoft Entra, Okta, Auth0, Google, …)
- Your tenant identifier (Entra Tenant ID, Okta org URL, Auth0 domain, etc.)
Tokens you mint must include the audience
https://api.example.com/v1.
Acme replies with their Microsoft Entra tenant ID:
a1f2c8de-4b9a-4d2e-9c1f-2b7e5a4c8d12
An operator at our end inserts a single row that links Acme's IdP tenant to their organisation record:
INSERT INTO ApiUserMemberships
(identityProvider, identityProviderId, clientOrganisationId, updatedOn)
VALUES
('microsoft',
'a1f2c8de-4b9a-4d2e-9c1f-2b7e5a4c8d12',
'<Acme organisationId>',
SYSUTCDATETIME());That's it. No code change. No redeploy. The auth guard reads this table on every request, so Acme is live on their next call.
The same shape is used for any provider:
identityProvider |
identityProviderId examples |
|---|---|
microsoft |
Entra Tenant ID (GUID) |
okta |
https://acme.okta.com |
auth0 |
acme.eu.auth0.com |
google |
Workspace customer ID or hosted domain |
Acme's backend requests an access token from Entra using the client-credentials grant:
POST https://login.microsoftonline.com/a1f2c8de-4b9a-4d2e-9c1f-2b7e5a4c8d12/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id=<acme-app-id>
&client_secret=<acme-app-secret>
&grant_type=client_credentials
&scope=https://api.example.com/v1/.defaultEntra returns a signed JWT whose decoded payload looks like:
{
"iss": "https://login.microsoftonline.com/a1f2c8de-4b9a-4d2e-9c1f-2b7e5a4c8d12/v2.0",
"tid": "a1f2c8de-4b9a-4d2e-9c1f-2b7e5a4c8d12",
"aud": "https://api.example.com/v1",
"sub": "<acme-app-id>",
"iat": 1747900000,
"exp": 1747903600
}The same flow works for any provider — Okta, Auth0, and Google all expose an equivalent token endpoint. The claims we care about are always the same: iss, aud, exp, and a tenant claim (tid, iss path, hd, …).
Acme makes their first request:
GET https://api.example.com/v1/records?filter[status]=in_progress
Authorization: Bearer <JWT from Scene 3>
Accept: application/vnd.api+jsonWhen the request lands, it passes through a fixed pipeline. Authentication runs first, then three layers of authorisation. If any step fails, the request is rejected before reaching the handler.
| # | What happens |
|---|---|
| 1 | Router matches GET /v1/records |
| 2 | AuthGuard.canActivate() extracts the bearer token |
| 3 | JWT decoded without verification; iss is read |
| 4 | Issuer pattern selects the provider — here, MicrosoftTokenProvider |
| 5 | Tenant claim (tid) is read from the unverified payload |
| 6 | Lookup in ApiUserMemberships: (microsoft, a1f2c8de-…) → Acme's organisationId ✅ |
| 7 | JWKS fetched (and cached) from the provider for that tenant |
| 8 | Signature verified against the matching key ✅ |
| 9 | aud validated against the expected audience ✅ |
| 10 | exp validated (with 30s clock-skew tolerance) ✅ |
| 11 | tid re-read from the verified payload and compared to step 5 ✅ |
| 12 | req.auth = { organisationId, providerType: 'microsoft', providerId: 'a1f2c8de-…' } |
The unverified-then-verified two-step is deliberate: we need a tenant hint to know which JWKS to fetch, but no decision is trusted until the signature checks out.
Once req.auth is set, the request reaches a route guard that asks:
"Is this organisation permitted to invoke this controller action on this resource type?"
This is a coarse gate. It answers questions like "can Acme read records?", "can Acme write submissions?", "is the admin/* namespace off-limits?". Denials here return 403 Forbidden immediately — the controller body never runs.
The controller runs, but every query is rewritten to add a row-level predicate derived from req.auth.organisationId. Conceptually:
const rows = await prisma.record.findMany({
where: {
AND: [
userFilter, // ?filter[status]=in_progress
entitlements.rowScope(req.auth.organisationId) // e.g. { ownerOrgId: <acme> }
],
},
});Acme sees Acme's rows. Never anyone else's. This is enforced in the data layer, not in the response shaper, so a missing filter on a controller cannot leak rows across tenants.
Before the response is serialised, each row passes through a visibility filter that strips properties Acme is not entitled to see. Two records of the same type can yield different JSON shapes for different callers — for example, a partner organisation might see record.score while the owner sees record.score and record.internalNotes.
return rows.map(row =>
entitlements.projectProperties(row, req.auth.organisationId)
);HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"type": "records",
"id": "rec_01J…",
"attributes": { "status": "in_progress", "title": "Q1 Report" }
}
]
}Acme's analytics job ingests the response, refreshes its dashboards, and moves on. The next run uses a fresh token from Entra. Operators on our side do zero manual work per request — the membership row from Scene 2 is the entire ongoing cost.
| Layer | Question it answers | Where it runs | Failure mode |
|---|---|---|---|
| Authentication | Who is calling, and can we trust the token? | AuthGuard, before any route |
401 Unauthorized |
| Controller & resource access | Is this caller allowed to invoke this action on this resource type? | Route guard, before handler | 403 Forbidden |
| Row-level entitlements | Which rows of this resource is the caller entitled to? | Query layer, inside handler | Rows silently excluded |
| Property-level visibility | Which properties of each row may the caller see? | Serialisation, before response | Properties silently omitted |
The four layers are independent. A caller can be authenticated, allowed to hit the controller, entitled to a row, and still receive a redacted view of it — and that is by design.
| Status | Meaning | Typical cause |
|---|---|---|
401 missing_token |
No Authorization header |
Header dropped by client/proxy |
401 invalid_signature |
JWKS verification failed | Token from wrong tenant; key rotated and client cached too aggressively |
401 invalid_audience |
aud didn't match |
scope parameter at the IdP not set to https://api.example.com/v1/.default (or your provider's equivalent) |
401 token_expired |
exp in the past |
Token not refreshed; clock skew beyond 30s |
401 tenant_not_registered |
(provider, tenantId) not in ApiUserMemberships |
Onboarding row missing or wrong tenant ID supplied |
403 resource_forbidden |
Layer 1 denied the action | Organisation not entitled to this controller/resource |
A 200 OK with an empty data array is not an error — it means the request was authorised but layer 2 (row-level) returned no matches.
- Tell support which IdP you use and your tenant identifier.
- Register an application in your IdP and grant it the client-credentials grant.
- Configure the application to request the audience/scope
https://api.example.com/v1/.default(or your provider's equivalent). - Wait for confirmation that your
ApiUserMembershipsrow has been created. - Mint a token, call
GET /v1/records, confirm you get a200. - Cache tokens until shortly before
exp— don't mint per request.
You're done.
During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com).To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs.
<Tip>Your preview updates automatically as you edit files.</Tip>
Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself.
1. Open `docs.json` in your editor.
2. Change the `"name"` field to your project name.
3. Update the `"colors"` to match your brand.
4. Save and see your changes instantly at `http://localhost:3000`.
<Tip>Try changing the primary color to see an immediate difference!</Tip>
Now that you have your docs running, explore these key features:
Learn MDX syntax and start writing your documentation. Make your docs match your brand perfectly. Include syntax-highlighted code blocks. Auto-generate API docs from OpenAPI specs. **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community).