Authentication

Use an API key for your own backend or automation. Use OAuth when your application asks other Make Agent Fast users to grant access. Both credential types call the same /api/v1 resources and obey the same scopes, plan entitlements, tenant isolation, and rate limits.

API keys#

An active paid plan is required to create and use a public API key.

1. Open Dashboard → Settings → Developer.
2. Enter a name that identifies the service and environment, such as Production lead export.
3. Select the minimum scopes the service needs.
4. Choose an expiry: 30 days, 90 days, one year, or never.
5. Create the key and copy the maf_live_... value immediately.

Make Agent Fast stores a SHA-256 hash rather than recoverable plaintext. The dashboard later shows a safe prefix, scopes, expiry, last-used time, and revocation state.

Authorization: Bearer maf_live_...

Send the header from server code:

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Missing credentials return 401 authentication_required. Invalid, expired, or revoked keys return 401 invalid_api_key. A key whose account no longer has an active paid plan returns 403 subscription_required.

Rotate or revoke a key#

Create a replacement before revoking the old key. Deploy the replacement, make a real request, verify its x-request-id, then click Revoke on the old key. Revocation is immediate and cannot be undone.

Scopes and expiry cannot be broadened on an existing key. Create a replacement so the permission change is explicit.

OAuth applications#

OAuth is for software connecting accounts owned by other Make Agent Fast users. It uses Authorization Code with PKCE (S256) and does not issue or require a client secret. The client ID is public; authorization codes, access tokens, refresh tokens, and the PKCE verifier are sensitive.

1. Register the application#

Open Dashboard → Settings → Developer → OAuth applications. Add:

• An application name from 2 to 100 characters.
• Between 1 and 10 exact redirect URLs.
• The maximum scopes your application may request.

Production redirect URLs must use HTTPS and cannot contain credentials or fragments. The complete URI must match a registered value during authorization and token exchange. Newly submitted applications have pending status; authorization works only after the application is reviewed and marked approved.

The platform owner reviews pending client IDs with the audited oauth:review workflow. Keep the client ID shown after submission; its status is visible on the Developer page, and rejected applications include the review decision before they can be resubmitted.

2. Generate PKCE values#

Generate a new verifier for every authorization attempt and keep it in the same protected, short-lived session as state.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

The verifier must contain 43–128 URL-safe PKCE characters. Only code_challenge_method=S256 is accepted.

3. Redirect the user for consent#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

The user signs in, reviews the requested scopes, and allows or denies access. On success, Make Agent Fast redirects to the exact registered URI with code and the original state. On denial it sends error=access_denied and the original state when one was supplied.

Reject the callback if state does not exactly match the value stored for that browser session.

4. Exchange the authorization code#

The authorization code expires after 10 minutes and can be used only once.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

The access token lasts one hour. The refresh token lasts up to 90 days unless it is rotated or revoked earlier.

5. Rotate the refresh token#

Every successful refresh revokes both the submitted refresh token and its previous access token, then returns a new pair. Save the new pair atomically before discarding the previous response state.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Reusing an authorization code or rotated refresh token returns invalid_grant. The OAuth token endpoint returns OAuth-style { "error", "error_description" } responses rather than the public API error envelope and allows 30 token requests per client and caller per minute.

Never authenticate management requests in browser code#

Do not put a secret API key, access token, or refresh token in React client components, static JavaScript, mobile web, Webflow, Framer, Wix, or Shopify Liquid. Use your authenticated backend. The public website embed uses a non-secret site slug and origin allowlist, not management API credentials.

See Credentials and tokens, Scopes and errors, and API quickstart.