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

# API Keys

> Create long-lived API keys to call the Mighty API as yourself from your own scripts and server-side jobs

## Overview

An **API key** is a long-lived credential a host of a Mighty Network creates to call the [Mighty API](/api) from their own scripts, scheduled jobs, and back-office automations. You send it as a Bearer token, exactly like an OAuth access token, but you skip the OAuth flow entirely: there's no OAuth application to register, no consent screen, no token exchange, and no refresh token.

Three properties define a key:

* **It acts as you.** Requests authenticated with a key see and do exactly what you, the host who created it, can see and do in the Network, limited to the scopes you granted the key.
* **It never expires.** A key keeps working until you revoke it.
* **It's shown once.** The key value is displayed only when you create it and can't be retrieved again. If you lose it, create another and revoke the old one.

<Note>
  The Mighty API is available on **Scale plans and above** (Scale, Growth and Mighty Pro). Only hosts of the Network can create, view, and revoke API keys; moderators and members can't.
</Note>

<Note>
  Looking for the Admin REST API's API keys? Those are a different credential for a different API. See [Admin API Authentication](/authentication).
</Note>

## When to use an API key

An API key and an [OAuth application](/oauth-applications) both produce a Bearer credential for the same GraphQL endpoint. Choose by **who the integration acts for**.

| | API key | OAuth application |
| - | - | - |
| **Acts as** | You, the host who created the key | Each user who signs in and approves it |
| **Who uses it** | Only you and the systems you run | Members, moderators, and hosts of the Network |
| **Scopes** | Host scopes only | Member scopes and host scopes |
| **Consent screen** | None | Shown to each user (unless skipped for a first-party app) |
| **Lifetime** | Never expires; ends when revoked | Short-lived access tokens, renewed with refresh tokens |
| **Set up in** | **Integrations** > **Mighty API** | **Integrations** > **OAuth Applications** |

Use an **API key** for work you run yourself, as yourself, against your own Network:

* Scripts and scheduled jobs that sync members, posts, or events to another system
* Data exports and reporting pipelines
* Back-office automations and internal tools only you operate
* AI agents or integrations you run on your own infrastructure that should act as you

Use an **OAuth application** when the integration acts **on behalf of other people**, or when people other than you use it: custom member apps, embeds, third-party products, anything that needs member scopes, a consent screen, short-lived tokens, or permissions that differ from user to user. See [Authentication](/api/authentication) for the OAuth flows.

## Create an API key

<Steps>
  <Step title="Open the Mighty API settings">
    Sign in to your Network as a host. Open **Network Admin**, then go to **Integrations** > **Mighty API**.
  </Step>

  <Step title="Start a new key">
    In the **API keys** card, click **New API Key**.
  </Step>

  <Step title="Name the key">
    Enter a **Name** that says what will use the key (for example, "Nightly CRM sync"). The name appears in the API keys list so you can tell your keys apart later.
  </Step>

  <Step title="Choose scopes">
    Select the [host scopes](#scopes) the key needs. A key reaches only what its scopes allow, so grant as few as the integration needs. You must select at least one scope.
  </Step>

  <Step title="Create the key">
    Click **Create key**.
  </Step>

  <Step title="Copy the key">
    In the **API key created** dialog, click the copy icon at the end of the key field and store the value in your secrets manager, then click **Done**.
  </Step>
</Steps>

<Warning>
  The key is shown once and can't be retrieved again. Treat it like a password: anyone holding it can act on your Network with the scopes you granted.
</Warning>

The **API keys** card lists up to 100 of the newest active keys in the Network with their **Name**, **Scopes**, **Created By**, **Created**, and **Last Used** time. **Last Used** updates shortly after each request the key authenticates.

## Scopes

A key can hold **host scopes only** — the scopes prefixed `host:`, such as `host:read:network_members` or `host:write:network_posts`. Member scopes such as `read:userinfo` or `write:posts` can't be granted to a key: a key already acts as you, so the host scopes cover what it can reach. For the full list of host scopes and what each one grants, see [OAuth Applications — Scopes](/oauth-applications#scopes).

* **Write scopes include their matching read.** A `host:write:network_posts` grant also satisfies anything that requires `host:read:network_posts`.
* **A key never exceeds your access.** It can do only what you can do as a host, and of that, only what its scopes cover.
* **Grant the least you need.** Because a key never expires, the scopes you choose are the access anyone holding it has for as long as it exists. Create one key per integration, each with its own narrow scope set, so you can revoke one without breaking the others.

## Use an API key

Pass the key as a Bearer token on every GraphQL request to your Network's endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.mn.co/networks/my-community/graphql \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "query { me { id name } }"
    }'
  ```

  ```javascript Node.js theme={null}
  const NETWORK = 'my-community';

  const response = await fetch(
    `https://api.mn.co/networks/${NETWORK}/graphql`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.MIGHTY_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        query: `query { me { id name } }`
      })
    }
  );

  const { data, errors } = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  NETWORK = "my-community"

  response = requests.post(
      f"https://api.mn.co/networks/{NETWORK}/graphql",
      headers={
          "Authorization": f"Bearer {os.environ['MIGHTY_API_KEY']}",
          "Content-Type": "application/json"
      },
      json={"query": "query { me { id name } }"}
  )

  payload = response.json()
  ```
</CodeGroup>

A key works only for the Network it was created in. The Network in the URL — its numeric ID or subdomain, as described in [Endpoint](/api#endpoint) — must be that Network.

## Revoke an API key

Revoke a key from the same card you created it in:

1. Go to **Network Admin** > **Integrations** > **Mighty API**.
2. In the **API keys** card, find the key and click the trash icon in its row.
3. Confirm with **Revoke**.

The key stops working immediately, and anything still using it starts failing. Revocation can't be undone; to restore access, create a new key and update the integration.

Keys are created and revoked only in Network Admin. A key isn't an OAuth token, so it can't be revoked at `/oauth/revoke`.

## Security and limits

* **Keys follow your host role.** On every request, Mighty checks that the key's creator is still a host of the Network and that their account is in good standing. If they're no longer a host, or their account is banned or removed, requests with the key fail even though the key hasn't been revoked. Revoke a person's keys when they leave the host role, and have the integration's new owner create their own.
* **Every authentication failure looks the same.** A malformed key, a revoked key, a key used against the wrong Network, and a key whose creator is no longer a host all return the same `401 Unauthorized` response.
* **Member emails depend on the plan and consent.** Another member's `Member.email` is `null` unless the Network's plan shows member emails to hosts. On a Network without SSO, the field returns an empty string (`""`) when the member hasn't agreed to share their email address. SSO Networks don't require that sharing consent, but the plan and scope rules still apply.
* **Scopes control email masking.** When another member's email has a value, a key returns it in plain text only with `host:read:network`, `host:read:network_members`, or `host:write:network_members`; otherwise it is obfuscated. An OAuth token acting as a host needs `read:userinfo` to return a visible address in plain text; host scopes alone don't unmask it.
* **Your own email bypasses the plan and sharing-consent checks for keys.** Your address (`me { email }`) is available through a key on any plan. The same key scope rule determines whether it is plain text or obfuscated.
* **Keep keys server-side.** Store keys in a secrets manager. Never put one in client-side code, a mobile or desktop app, a browser bundle, a log, or version control. If a key may have leaked, revoke it and create a replacement.

## Next steps

<CardGroup cols={2}>
  <Card title="Mighty API" icon="diagram-project" href="/api">
    Endpoint, request format, errors, and the schema reference.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Use OAuth 2.0 when your integration acts on behalf of other users.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.