Authentication

All NueForm API requests require authentication via API keys. This guide covers how to generate keys, use them in requests, and keep them secure.

Generating API Keys

To create an API key:

1. Sign in to your NueForm account.
2. Navigate to Profile and open the Developer tab.
3. Click Create API Key.
4. Give your key a descriptive name (e.g., "Production Backend" or "CI Pipeline").
5. Copy the key immediately --- it will only be displayed once.

API Key Format

NueForm API keys follow a consistent format:

nf_<64 hex characters>

Every key begins with the prefix nf_ followed by 64 hexadecimal characters (32 random bytes). For example:

nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

In the dashboard, keys are identified by their prefix (the first 11 characters, e.g., nf_a1b2c3d4) so you can tell them apart without exposing the full value.

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer nf_your_api_key_here

cURL

curl -X GET https://app.nueform.com/api/v1/forms \
  -H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;

const response = await fetch("https://app.nueform.com/api/v1/forms", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${NUEFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();
console.log(data);

Python (requests)

import os
import requests

api_key = os.environ["NUEFORM_API_KEY"]

response = requests.get(
    "https://app.nueform.com/api/v1/forms",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]
print(data)

Authentication Errors

If authentication fails, the API returns a 401 Unauthorized response with a descriptive message:

Example error response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

Key Management

Limits

Each NueForm account can have up to 10 active API keys at any time. If you need to create a new key and have reached the limit, revoke an existing key first.

Revoking Keys

You can revoke an API key at any time from the Developer tab in your profile. Revocation is immediate --- any request using a revoked key will receive a 401 Unauthorized response.

To revoke a key:

1. Go to Profile > Developer.
2. Find the key you want to revoke (identified by its name and prefix).
3. Click Revoke.
4. Confirm the action.

Last Used Tracking

NueForm tracks the last time each API key was used. Check the Developer tab to see which keys are actively in use and which may be safe to revoke.

Plan Requirements

API access is a gated feature that requires a paid plan:

If you attempt to use an API key on an account whose plan does not include API access, you will receive a 403 Forbidden response:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

Security Best Practices

Follow these guidelines to keep your API keys safe:

Never commit keys to version control

Add your key files to .gitignore and use environment variables instead. If a key is accidentally committed, revoke it immediately and generate a new one.

# .env (add .env to your .gitignore)
NUEFORM_API_KEY=nf_your_api_key_here

Use environment variables

Store API keys in environment variables in every environment --- local development, staging, and production. Never hard-code keys into your application source.

// Good
const apiKey = process.env.NUEFORM_API_KEY;

// Bad --- never do this
const apiKey = "nf_a1b2c3d4...";

Use separate keys for each environment

Create distinct API keys for development, staging, and production. This limits the blast radius if a key is compromised and makes it easy to revoke a single environment's access.

Rotate keys regularly

Periodically create new keys and phase out old ones. NueForm allows up to 10 active keys, so you can create a new key, update your services, verify everything works, and then revoke the old key.

Restrict server-side usage only

API keys should only be used in server-side code. Never expose your API key in client-side JavaScript, mobile apps, or any code that runs in a user's browser.