Skip to content

Latest commit

 

History

History
305 lines (217 loc) · 12 KB

quickstart.mdx

File metadata and controls

305 lines (217 loc) · 12 KB
title Quickstart
description Start building awesome documentation in minutes
icon rocket

Getting Started

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.


How authentication works (in one paragraph)

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.


Scene 1 — First contact

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:

  1. Your IdP type (Microsoft Entra, Okta, Auth0, Google, …)
  2. 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

Scene 2 — Onboarding

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

Scene 3 — Mint a token

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/.default

Entra 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, …).


Scene 4 — Call the API

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+json

Scene 5 — Our service handles the request

When 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.

Step A — Authentication (AuthGuard)

# 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.

Step B — Authorisation, layer 1: controller & resource access

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.

Step C — Authorisation, layer 2: row-level entitlements

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.

Step D — Authorisation, layer 3: property-level visibility

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)
);

Step E — Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "records",
      "id": "rec_01J…",
      "attributes": { "status": "in_progress", "title": "Q1 Report" }
    }
  ]
}

Scene 6 — The pipeline runs

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.


Reference: the layered model at a glance

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.


Common errors

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.


Checklist for going live

  1. Tell support which IdP you use and your tenant identifier.
  2. Register an application in your IdP and grant it the client-credentials grant.
  3. Configure the application to request the audience/scope https://api.example.com/v1/.default (or your provider's equivalent).
  4. Wait for confirmation that your ApiUserMemberships row has been created.
  5. Mint a token, call GET /v1/records, confirm you get a 200.
  6. 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.
1. Install the Mintlify CLI: `npm i -g mint` 2. Navigate to your docs directory and run: `mint dev` 3. Open `http://localhost:3000` to see your docs live!
<Tip>Your preview updates automatically as you edit files.</Tip>

Step 2: Deploy your changes

Install the Mintlify GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app).
Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself.
For a first change, let's update the name and colors of your docs site.
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>

Step 3: Go live

1. Commit and push your changes. 2. Your docs will update and be live in moments!

Next steps

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).