Falaah Falaah AI

API Keys and Authentication

Create a Muin API key, choose Read or Write scope, send it as a Bearer token, and fix 401, 403 and 429 errors. Also covers OAuth sign-in for AI apps.

An API key lets a script or another system call Muin as you, without a browser sign-in.

When you’d use this

  • A nightly script exports invoices or registrations into another system.
  • Your server manages webhooks through the API.
  • A tool with no browser, such as Claude Code or a CI job, connects to the MCP server.

For an AI app that can open a browser, such as Claude, use the sign-in flow instead of a key. See OAuth sign-in for apps below.

Create an API key

Owners and admins can create keys.

  1. Open Settings → Integrations → API Keys.
  2. Click Create API Key.
  3. Fill in:
    • Name, for example “CI/CD Pipeline”.
    • Scopes: Read (ticked by default) and, only if the key must change data, Write.
    • Expires: 30 days, 90 days (the default), 180 days, 1 year, or No expiration. A key with no expiration works until someone revokes it. Through the API, an omitted expires_in_days means 90 days and null means no expiration.
  4. Click Create. Muin asks you to confirm with multi-factor authentication if you have not done so recently.
  5. Copy the key now. It is shown once and cannot be retrieved later.

Keys start with muin_ followed by 64 characters.

Make an authenticated request

Send the key as a Bearer token:

curl https://muin-api.falaah.ai/api/v1/webhooks/outgoing \
  -H "Authorization: Bearer muin_your_api_key_here"

The key acts as the person who created it, inside that person’s organization. It can never reach another organization.

Scopes

Scope Allows
Read (read) GET, HEAD and OPTIONS requests
Write (write) Requests that change data: POST, PUT, PATCH, DELETE

A key also cannot do more than the person who created it. A Write key made by someone without permission to manage webhooks still gets 403 on webhook changes.

No scope, not even Write, lets a key change how people sign in or who has access. Sign-in and sessions, MFA, other API keys, members, roles, invitations, billing, single sign-on and directory sync all return 403 with API keys cannot manage sign-in, sessions, keys, members, roles, billing or single sign-on. Do those in the Muin app. GET /api/v1/auth/me works with any key, so you can check which account a key acts as.

Daily request limit

API-key requests count against a daily limit set by your plan. The Daily API requests meter on the API Keys screen shows how many are left and when the count resets (midnight UTC). Plans with no limit show No daily limit on your plan. See Pricing for each plan’s allowance.

What it affects

  • Each key’s page shows Scopes, Created, Expires and Last Used.
  • Calls made with a key count toward your organization’s daily request limit.
  • A key stops working on its own when its owner is deactivated or removed, when an admin signs everyone out, or when the organization is suspended.

Rotate or revoke a key

  • Rotate: open the key and click Rotate. Muin issues a new key with the same name, scopes and expiration, and the old key stops working immediately. Update your script with the new key at the same time.
  • Revoke: click Revoke on the key (or Revoke key in the list). It stops working at once and cannot be undone.

When it goes wrong

Status Why What to do
401 The key is missing, mistyped, revoked or expired. Check the Authorization: Bearer muin_... header, or create a new key.
401 with a message about the workspace or user The key’s owner was deactivated or removed, an admin signed everyone out, or the organization is suspended. The message says which. Ask an admin to issue a new key from an active account.
403 The key lacks the scope the request needs (a Read key sending POST), its owner lacks permission for that screen, or the request manages sign-in or access, which no key may do. Create a key with Write, from an owner or admin account.
429 You reached your plan’s daily request limit. Wait for the reset shown on the Daily API requests meter, or upgrade your plan.

OAuth sign-in for apps

AI apps that connect to the MCP server can sign in instead of using a key. The person approving sees Muin’s approval screen and chooses Allow access (what that screen shows).

For developers building such an app:

Item Value
Server metadata https://muin-api.falaah.ai/.well-known/oauth-authorization-server
Protected resource metadata https://muin-api.falaah.ai/.well-known/oauth-protected-resource
Client registration POST /api/v1/oauth/register (dynamic client registration)
Authorize, token, revoke /api/v1/oauth/authorize, /api/v1/oauth/token, /api/v1/oauth/revoke
Grant types authorization_code with PKCE (S256 only), and refresh_token
Scopes read, write
Lifetimes Access tokens last 1 hour; the connection lasts 90 days unless the app refreshes it

Tokens from this flow work only on the MCP server. People can review and end every app’s access at Settings → Integrations → Connected apps.

Security practices

  • Keep keys on your server, never in browser code or a mobile app.
  • Store keys in environment variables, not in source code.
  • Give each system its own key so you can revoke one without breaking the others.
  • Set an expiration and rotate keys on a schedule.

Next step