Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mightynetworks.com/llms.txt

Use this file to discover all available pages before exploring further.

Alpha Release: The Headless API and its documentation are currently in alpha and subject to change. Schemas, fields, and behavior may be modified or updated without notice.

​
Overview

An OAuth application is the credential a third-party app uses to ask members, hosts, and admins of a Mighty Network for permission to act on their behalf. It is the entry point to the Headless API: every access token the Headless API issues comes from a user authorizing one of your OAuth applications. You create an OAuth application once per integration, in the network it should operate against. The application owns:
  • A Client ID that identifies the app on every authorization request.
  • A Client Secret (for confidential clients) that authenticates the app when exchanging an authorization code for a token.
  • One or more Redirect URIs the authorization server is allowed to redirect back to after a user approves access.
  • A set of Scopes the application is permitted to request — the upper bound on what an issued token can do.
Creating OAuth applications is available on Scale plans and above (Scale, Growth and Mighty Pro). The Headless API is in alpha and is being rolled out incrementally. If you don’t see Integrations > OAuth Applications in Network Admin, your network isn’t in the rollout yet.

​
Create an OAuth application

OAuth applications are created and managed from Network Admin.
1

Open Integrations settings

Sign in to your network as a host or admin. Open Network Admin, then go to Integrations > OAuth Applications.
2

Start a new application

Click New OAuth Application.
3

Name the application

Enter a Name for the application. The name is shown to users on the consent screen — pick something a member would recognize as the integration they’re authorizing (for example, the product or company name).
4

Choose a client type

Select Confidential if the application runs on a server you control and can keep a secret (a web backend, a back-office job, a server-to-server integration).Select Public if the application runs on a device you don’t control (a native mobile app, a desktop app, a single-page web app). Public clients do not receive a Client Secret and must use the Authorization Code flow with PKCE.
5

Add redirect URIs

Enter the URL the authorization server is allowed to redirect users back to after they approve or deny the request. To register multiple URIs (one per environment — production, staging, local development), enter them in a single field separated by newlines. Redirect URIs are matched exactly — including scheme, host, port, and path.Local development URLs (http://localhost:3000/oauth/callback) are accepted. All other redirect URIs must use https.
6

Select member scopes

Choose the member scopes the application is allowed to request — these govern access to the authorized user’s own content (their posts, comments, courses, profile).
7

Select host scopes

Choose the host scopes the application is allowed to request — these grant network-wide reads and only take effect when the authorized user is a host of the network. Leave empty if your integration doesn’t act on behalf of hosts.Across both scope fields, request the narrowest set that lets the feature work. The application can request any subset of the configured scopes per authorization, but never more — and users see the full list on the consent screen, so broader scopes drive higher abandonment.
8

Copy your credentials

Mighty issues a Client ID and (for confidential clients) a Client Secret.The Client Secret is shown once and cannot be recovered. Copy it into your secret store before leaving the page. If you lose it during alpha, delete the application and create a new one (programmatic secret rotation will land before GA).
The Client Secret is bearer credential material. Never embed it in mobile apps, single-page apps, browser bundles, or anywhere it could be read by a user agent. For public clients, use the Authorization Code flow with PKCE and skip the secret entirely.

​
Configuration

​
Redirect URIs

The authorization server only redirects back to URIs registered on the application. The match is exact — https://example.com/cb will not match https://example.com/cb/, https://example.com/cb?x=1, or https://www.example.com/cb. Register every variant your app uses. Multiple URIs are registered as a single newline-separated value. Guidelines:
  • One URI per environment (production, staging, dev, local), separated by newlines.
  • Use https for everything except http://localhost and http://127.0.0.1.
  • Avoid open redirectors. The registered URI should point at an endpoint your app controls and that validates the state parameter before issuing the token exchange.

​
Scopes

Scopes are coarse permissions an application can ask a user to grant. The token the Headless API issues is the intersection of the scopes the user approves and what that user can do in the product. A read:posts scope granted to a member only exposes what the member could already see; a host:read:network_posts scope is only effective when the authorized user is a host of the network. Scopes split into two families: member scopes that govern access to the authorized user’s own content, and host scopes (prefixed host:) that grant network-wide reads and only take effect when the authorized user is a host of the network.
If a host scope is requested on an authorization request, only hosts of the network will be able to complete the flow — non-host users (members, moderators) are blocked at the consent screen and cannot sign in to your application. Configure host scopes only on applications meant for host-facing integrations, and request them only on authorization requests where the user is expected to be a host.
Member scopes:
ScopeDescription
read:userinfoView the user’s basic profile information.
read:postsView posts the user has created.
read:coursesView the user’s courses and course progress.
read:searchSearch network content on the user’s behalf.
write:postsCreate, edit, and delete posts on the user’s behalf.
write:commentsCreate, edit, and delete comments on the user’s behalf.
Host scopes (effective only for hosts):
ScopeDescription
host:read:network_eventsView events in the network.
host:read:network_spacesView spaces in the network.
host:read:network_membersView members in the network.
host:read:network_plansView plans in the network.
host:read:network_postsView posts in the network.
The catalog above reflects alpha and will grow before GA. The Scopes panel in the OAuth application form is the source of truth for what’s currently selectable and shows the per-scope descriptions users see on the consent screen.

​
Client type

Client typeReceives secretAuth methodUse it for
ConfidentialYesclient_secret on /oauth/tokenServer-side web apps, back-office jobs, machine-to-machine flows
PublicNoPKCE (code_verifier) on /oauth/tokenNative mobile apps, desktop apps, single-page web apps, CLIs
If you’re unsure, choose Public + PKCE. PKCE is also recommended for confidential clients — Mighty’s authorization server accepts code_verifier alongside client_secret for defense in depth.

​
Using your credentials

Once the application is created, use the Client ID (and Secret, if confidential) to drive the Authorization Code flow against your network’s OAuth endpoints. OAuth endpoints are served from the network’s community host (not api.mn.co): 
https://:network_subdomain.mn.co/oauth/authorize
https://:network_subdomain.mn.co/oauth/token
The canonical endpoint URLs are also advertised at https://:network_subdomain.mn.co/.well-known/oauth-authorization-server (RFC 8414). For the complete request/response shapes — including PKCE, state, refresh tokens, and error handling — see Authentication and the OAuth flow walkthrough in Headless API. 
https://my-community.mn.co/oauth/authorize\
?response_type=code\
&client_id=YOUR_CLIENT_ID\
&redirect_uri=https://app.example.com/oauth/callback\
&scope=read:userinfo+read:posts\
&state=RANDOM_OPAQUE_STRING\
&code_challenge=PKCE_CHALLENGE\
&code_challenge_method=S256
A successful token exchange returns an access_token, refresh_token, expires_in, and the granted scope. Pass the access_token as a Bearer token on every Headless API request.

​
Manage an existing application

​
Edit configuration

From Network Admin > Integrations > OAuth Applications, open an application to update its name, redirect URIs, or allowed scopes. Configuration changes take effect on the next authorization request — existing access tokens are unaffected until they expire. Tightening scopes does not retroactively narrow tokens that have already been issued. To revoke broad access immediately during alpha, delete the application.

​
Delete the application

To permanently retire an OAuth application:
  1. Open the application from Network Admin > Integrations > OAuth Applications.
  2. Click Delete application.
  3. Confirm.
Deleting the application invalidates the Client ID, the Client Secret, and every access and refresh token ever issued under it. This action cannot be undone.
Programmatic client-secret rotation and per-token revocation are not yet exposed in alpha. Until they ship, the supported way to invalidate a leaked secret or kill an outstanding token is to delete the application (which revokes every token under it) and create a replacement. Both capabilities will land before GA.

​
Security best practices

  • Treat the Client Secret like a password. Store it in a secret manager (1Password, AWS Secrets Manager, GCP Secret Manager, Vault). Never check it into source control or ship it in a client bundle.
  • Use PKCE everywhere. Public clients must use PKCE; confidential clients should too.
  • Validate state. Generate a cryptographically random state per authorization request and reject any callback whose state doesn’t match.
  • Pin redirect URIs. Register the exact URIs your app uses. Never register a wildcard, a path you don’t control, or an open redirector.
  • Request least privilege. Ask for the narrowest scopes that let the feature work. Broader scopes increase consent abandonment and expand the blast radius if a token leaks.
  • Replace applications on suspicion of secret leak. During alpha, programmatic secret rotation is not yet available. If a secret may have leaked — a former contributor with access, a misconfigured log, a compromised build — delete the application (which revokes every token under it) and create a replacement.

​
Troubleshooting

​
invalid_client on token exchange

  • Check that the Client ID matches the application exactly.
  • For confidential clients, verify the Client Secret hasn’t been rotated out from under the deployment.
  • For public clients, make sure you’re sending code_verifier and not client_secret.

​
invalid_grant on token exchange

  • The authorization code is single-use and expires within a minute or two — make sure you’re not retrying with a code that’s already been redeemed.
  • The redirect_uri sent to /oauth/token must exactly match the one used to obtain the code.
  • For PKCE, the code_verifier must match the code_challenge originally sent.

​
redirect_uri_mismatch on authorize

  • The redirect_uri query parameter must exactly match one of the URIs registered on the application — scheme, host, port, and path all included.
  • The consent screen reflects the application’s Name field. Update it in Network Admin > Integrations > OAuth Applications > your app.

​
Next steps

Headless API

Use your access token against the GraphQL API.

Authentication

OAuth flows, scopes, and token lifecycle in detail.