Authentication

Overview

The Mighty API authenticates requests with OAuth 2.0 or with an API key. With OAuth, a third-party application redirects a user to Mighty, the user signs in and approves a set of scopes, and your application receives a short-lived access token that acts on behalf of that user against the GraphQL API. This is fundamentally different from the Admin REST API, which uses a long-lived Bearer token tied to a Network admin. Pick the one that matches your integration:

	Admin REST API	Mighty API
Acts as	A specific Network admin	Any authorized member, moderator, or host
Credential	Long-lived API token	Short-lived OAuth 2.0 access token, or a host’s own long-lived API key
Issued to	A single admin user	An OAuth application + an end user, or a host (API key)
Use it for	Back-office automation, integrations, analytics	Member experiences, host and admin tools, agents, embeds

Why OAuth 2.0

The Mighty API is designed for third-party applications that act on behalf of an end user — a member reading their feed in a custom mobile app, a host pulling their Network into a back-office dashboard, an AI agent summarizing a space the user belongs to. The auth model has to answer two questions a static API key can’t:

Whose data is this? Every Mighty API call resolves against a specific user’s permissions in a specific Network. A member token can only see what that member can already see in the product; a host token additionally exposes host-level fields. There is no “superuser” mode and no way for a third-party app to read data the authorized user can’t.
Did the user actually consent? Before an application receives a token, the user is shown a consent screen listing the application name and the scopes it’s requesting, and explicitly approves. Mighty — not the application — collects the password. The application never sees the user’s credentials and can never act beyond the scopes the user approved.

OAuth 2.0 is the industry-standard protocol that solves both of these. Concretely, it gives us:

Delegated access without credential sharing. Users authorize applications through Mighty’s login flow. Applications never handle passwords, MFA codes, or session cookies.
Scoped, revocable tokens. Tokens are bound to a specific user, application, and scope set, with a short expiry. A leaked token has a small blast radius; users (and hosts) can revoke an application’s access without rotating their password.
A model that fits every client type. Server-side web apps use the Authorization Code flow with a client secret. Mobile, desktop, and single-page apps use Authorization Code + PKCE and ship no secret at all. Both target the same authorization server and the same token endpoint.
An ecosystem of tooling. OAuth 2.0 client libraries exist for every language and framework — there’s no Mighty-specific SDK to learn, and standard tools (Postman, curl, framework auth middleware) work out of the box. Mighty publishes the canonical endpoints at /.well-known/oauth-authorization-server per RFC 8414.

A static key can’t do this job: it acts as whoever created it, so an app built on keys would either act as the host for everyone (no per-user permissions, no consent) or make every end user mint and paste their own (no consent UI, no scope control, terrible UX). OAuth 2.0 is the off-the-shelf answer to “let third-party apps act as my users, with their consent, scoped to what they approved, revocable at any time.” When the only user is you — a host calling the API from your own scripts and jobs — that trade-off disappears, and an API key is the simpler credential.

Create an OAuth application

Before your app can request tokens, a host or admin must register an OAuth application in the Network. The application provides the Client ID (and, for confidential clients, Client Secret) you’ll use in the flows below, along with the redirect URIs and allowed scopes. For the full walkthrough — client types, redirect URI rules, scope catalog, secret rotation, and revocation — see OAuth Applications.

API keys

If your integration only ever acts as you, a host of the Network — a script, a scheduled job, a data export — you don’t need an OAuth application. Create an API key under Network Admin > Integrations > Mighty API and send it as a Bearer token, exactly like an access token. A key carries host scopes only, acts as the host who created it, and never expires, so there’s no token exchange, refresh, or /oauth/revoke call; you revoke it from Network Admin. See API Keys for when to choose a key and how to create one.

Endpoints

OAuth endpoints are served from the Network’s community host, not from api.mn.co:

https://:network_subdomain.mn.co/oauth/authorize
https://:network_subdomain.mn.co/oauth/token
https://:network_subdomain.mn.co/oauth/revoke

The canonical endpoint URLs are also advertised at:

https://:network_subdomain.mn.co/.well-known/oauth-authorization-server

per RFC 8414. Standard OAuth client libraries that support discovery will pick these up automatically.

Authorization Code flow

The standard flow for user-facing apps. Public clients (mobile, desktop, single-page) must add PKCE; confidential clients (server-side web apps) should use PKCE in addition to their client secret.

Step 1 — Redirect to the authorization endpoint

https://:network_subdomain.mn.co/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=SPACE_SEPARATED_SCOPES
  &state=RANDOM_OPAQUE_STRING
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Parameter	Required	Description
`response_type`	Yes	Must be `code`.
`client_id`	Yes	The Client ID from your OAuth application.
`redirect_uri`	Yes	Must exactly match a URI registered on the application (scheme, host, port, path).
`scope`	Yes	Space-separated list of scopes — see scopes.
`state`	Yes	Cryptographically random, single-use nonce generated per authorization request (e.g. 32 bytes from a CSPRNG, base64url-encoded). Bind it to the user’s session and verify the value returned on the redirect matches — this is required to prevent CSRF.
`code_challenge`	Public clients (recommended for confidential)	PKCE challenge derived from a `code_verifier` your app holds.
`code_challenge_method`	If `code_challenge` is sent	Use `S256`.
`require_host`	No	Whether only a host of the Network may complete the flow. Send `false` to let members and moderators sign in to a request that includes host scopes; they’re granted its member scopes only. Send `true` to require a host even when you request no host scope. Omit it, and a host is required exactly when you request a host scope. See host scopes and sign-in.

Step 2 — User approves

The user signs in (if they aren’t already) and approves the requested scopes on the consent screen. Mighty redirects back to your redirect_uri with:

https://app.example.com/oauth/callback?code=AUTH_CODE&state=YOUR_STATE&iss=https%3A%2F%2Fmy-community.mn.co

Before exchanging the code, verify that the state returned on the redirect exactly matches the cryptographically random nonce you generated for this request and bound to the user’s session. If it’s missing, doesn’t match, or has already been used, reject the callback and do not call /oauth/token — an attacker may be trying to forge an authorization on the user’s behalf (CSRF).

Mighty also includes an iss parameter on every authorization response, per RFC 9207. Its value matches the issuer in the Network’s /.well-known/oauth-authorization-server metadata. If your client uses more than one authorization server, reject any callback whose iss doesn’t match the server you started the request with.

Step 3 — Exchange the code for an access token

curl https://:network_subdomain.mn.co/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=PKCE_VERIFIER"

curl https://:network_subdomain.mn.co/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=PKCE_VERIFIER"

A successful response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "scope": "read:userinfo read:network"
}

The scope field reflects what was actually granted — the intersection of what the application is allowed to request, what the user approved, and what the user is permitted to do in the product. Always check it; don’t assume you got everything you asked for.

Step 4 — Call the Mighty API

Pass the access token as a Bearer token on every GraphQL request:

POST /networks/my-community/graphql HTTP/1.1
Host: api.mn.co
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
User-Agent: my-app/1.0 (+https://example.com)

{ "query": "query { me { id name } }" }

Refreshing tokens

Access tokens are short-lived (expires_in is returned with each token, typically one hour). When a token expires, exchange the refresh token for a new pair:

curl https://:network_subdomain.mn.co/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Public clients omit client_secret. The response shape matches the original token response; the refresh token may rotate, so always persist the new value if one is returned. Refresh tokens are themselves long-lived but not permanent. They are invalidated when:

The user revokes the application’s access.
A host deletes the OAuth application.
The user changes their password or is signed out network-wide.
The refresh token reaches its absolute lifetime.
Your application revokes the token pair at /oauth/revoke.

When a refresh attempt returns invalid_grant, the user must re-authorize — kick them back through Step 1.

Revoking tokens

/oauth/revoke implements RFC 7009 and accepts either an access token or a refresh token in the token parameter. Access and refresh tokens are issued as a pair, so revoking either one revokes both. The caller must be the application the token was issued to: public clients send client_id only, and confidential clients send client_id and client_secret. Call it when the user signs out.

curl https://:network_subdomain.mn.co/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Public clients omit client_secret. The endpoint returns HTTP 200 whether or not the token was valid, as RFC 7009 requires. For when to revoke in each client architecture, see Token handling.

Scopes and permissions

The access token grants exactly the access the underlying user has in the product, intersected with the scopes the user approved.

A read:network scope granted to a member only exposes what the member could already see in the product.
A host:read:network_posts scope is only effective when the authorized user is a host of the Network — a member who approves it still won’t get host-level reads.
The read:chats and write:chats scopes expose the member’s private conversations, so they always require the member’s explicit consent — the consent screen cannot be skipped for them.

For the full scope catalog and per-scope descriptions, see OAuth Applications — Scopes. By default, if your authorization request includes any host scope (any scope prefixed host:), only hosts of the Network can complete sign-in. Members and moderators are blocked at the consent screen and cannot obtain a token. If your application serves both hosts and members, add require_host=false to the authorization request and ask for the member and host scopes you want in one flow. A host is granted everything requested. A member or moderator signs in normally and is granted only the member scopes, and their consent screen lists only those. Read the scope field of the token response to learn which set the user received.

`require_host`	Host signs in	Member or moderator signs in
Omitted	Granted everything requested	Blocked if any host scope is requested; otherwise granted everything requested
`false`	Granted everything requested	Granted the member scopes only; blocked if you requested host scopes only
`true`	Granted everything requested	Blocked, even when you request no host scope

Only the exact value false relaxes the requirement. An empty value counts as omitted, and any other value, such as 0 or False, is treated as true.

Send require_host=false only if your application reads the granted scope from the token response. Without that check, a member’s token looks like a host’s until host-scoped calls start failing with permission errors.

Errors

OAuth errors follow RFC 6749. The authorization endpoint returns errors via redirect query string; the token endpoint returns them as JSON with a 400 (or 401 for client auth failures).

Error	Where	Common cause
`invalid_request`	Both	Missing or malformed parameter.
`invalid_client`	`/oauth/token`	Wrong Client ID, wrong Client Secret, or sending a secret on a public client.
`invalid_grant`	`/oauth/token`	Authorization code already used, expired, or redeemed against a different `redirect_uri`; PKCE verifier doesn’t match the challenge; refresh token revoked or expired.
`unauthorized_client`	Both	The application isn’t allowed to use this grant type.
`unsupported_grant_type`	`/oauth/token`	`grant_type` is not `authorization_code` or `refresh_token`.
`invalid_scope`	`/oauth/authorize`	Requested a scope the application isn’t configured for.
`access_denied`	`/oauth/authorize`	The user declined the consent screen.
`redirect_uri_mismatch`	`/oauth/authorize`	`redirect_uri` does not exactly match a registered URI.

For GraphQL request errors (expired token, missing scope, insufficient permission), see Mighty API error handling.

Security best practices

Choose an architecture that fits where your code runs. That choice determines the client type, redirect URI, and token storage. See OAuth Client Architectures.
Use PKCE everywhere. Required for public clients; recommended for confidential clients as defense in depth.
Always send and validate state. It’s a required parameter on /oauth/authorize. Generate a cryptographically random, single-use nonce per authorization request, bind it to the user’s session, and reject any callback whose state is missing or doesn’t match. This is your CSRF defense — skipping it lets an attacker trick a signed-in user into linking the attacker’s authorization code to their account.
Validate iss on the callback. Reject any authorization response whose iss doesn’t match the Network’s issuer, per RFC 9207.
Pin redirect URIs. Register the exact URIs your app uses. Never register a wildcard, a path you don’t control, or an open redirector.
Treat the Client Secret like a password. Store it in a secret manager, never in source control, never in a client bundle. Never ship a secret in a mobile, desktop, or single-page app — use the public client type with PKCE instead.
Request least privilege. Ask for the narrowest scopes that let the feature work. Broader scopes drive higher consent abandonment and expand the blast radius if a token leaks.
Persist refresh tokens server-side. Refresh tokens are long-lived credentials. Store them encrypted at rest and never expose them to the browser or to logs.
Replace applications on suspicion of secret leak. Programmatic secret rotation is not currently available. If a secret may have leaked, delete the application (which revokes every token under it) and create a replacement.

Next steps

OAuth Applications

OAuth Client Architectures

Choose an architecture for each client type and avoid the token proxy anti-pattern.

Mighty API

Use your access token against the GraphQL API.

Overview

Integration guides

Queries

Mutations

Types

Overview

Why OAuth 2.0

Create an OAuth application

API keys

Endpoints

Authorization Code flow

Step 1 — Redirect to the authorization endpoint

Step 2 — User approves

Step 3 — Exchange the code for an access token

Step 4 — Call the Mighty API

Refreshing tokens

Revoking tokens

Scopes and permissions

Errors

Security best practices

Next steps

OAuth Applications

OAuth Client Architectures

Mighty API

​Overview

​Why OAuth 2.0

​Create an OAuth application

​API keys

​Endpoints

​Authorization Code flow

​Step 1 — Redirect to the authorization endpoint

​Step 2 — User approves

​Step 3 — Exchange the code for an access token

​Step 4 — Call the Mighty API

​Refreshing tokens

​Revoking tokens

​Scopes and permissions

​Host scopes and sign-in

​Errors

​Security best practices

​Next steps

OAuth Applications

OAuth Client Architectures

Mighty API

Overview

Why OAuth 2.0

Create an OAuth application

API keys

Endpoints

Authorization Code flow

Step 1 — Redirect to the authorization endpoint

Step 2 — User approves

Step 3 — Exchange the code for an access token

Step 4 — Call the Mighty API

Refreshing tokens

Revoking tokens

Scopes and permissions

Host scopes and sign-in

Errors

Security best practices

Next steps