API Authentication

API Authentication

The NEURO API uses Bearer token authentication. This guide explains how to obtain and use API tokens.

Token Types

Type	Use Case	Expiration
Personal Token	Individual user access	Configurable
Service Token	Application integrations	Long-lived

Creating an API Token

Personal Token

1. Log into NEURO
2. Go to Settings → API Access
3. Click + Create Token
4. Configure token:
   • Name: Descriptive name
   • Expiration: Never, 30 days, 90 days, 1 year
   • Scopes: Select permissions
5. Click Create
6. Copy the token immediately - it won’t be shown again

Service Token (Admin Only)

For application integrations:

1. Go to Settings → Integrations → API Tokens
2. Click + Create Service Token
3. Configure token settings
4. Assign to a service account

Using Tokens

HTTP Header

Include the token in the Authorization header:

curl -X GET "https://{tenant}.nforged.com/api/v1/projects" \
  -H "Authorization: Bearer nf_live_abc123..."

Request Examples

cURL

# List projects
curl -X GET "https://{tenant}.nforged.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create finding
curl -X POST "https://{tenant}.nforged.com/api/v1/findings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "proj_123", "title": "SQL Injection"}'

Python

import requests

API_TOKEN = "nf_live_abc123..."
BASE_URL = "https://{tenant}.nforged.com/api/v1"  # Replace {tenant} with your subdomain

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# List projects
response = requests.get(f"{BASE_URL}/projects", headers=headers)
projects = response.json()["data"]

JavaScript

const API_TOKEN = 'nf_live_abc123...';
const BASE_URL = 'https://{tenant}.nforged.com/api/v1';  // Replace {tenant} with your subdomain

const response = await fetch(`${BASE_URL}/projects`, {
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});
const { data: projects } = await response.json();

Token Scopes

Limit token permissions with scopes:

Scope	Access
projects:read	View projects
projects:write	Create/edit projects
findings:read	View findings
findings:write	Create/edit findings
reports:read	View/download reports
reports:write	Generate reports
assets:read	View assets
assets:write	Create/edit assets
admin	Administrative access

Scope Examples

Read-only integration:

projects:read, findings:read, assets:read

CI/CD automation:

findings:write, assets:write

Full access:

admin

Token Security

Best Practices

• • Use minimal scopes needed
• • Set expiration dates
• • Use environment variables
• • Rotate tokens periodically
• • Monitor token usage

What NOT to Do

• • Commit tokens to source control
• • Share tokens between users
• • Use admin scope unnecessarily
• • Ignore token expiration

Environment Variables

Store tokens securely:

# .env file (never commit)
NFORGED_API_TOKEN=nf_live_abc123...

import os
token = os.environ.get('NFORGED_API_TOKEN')

Managing Tokens

View Active Tokens

1. Go to Settings → API Access
2. See list of your tokens
3. View last used date

Revoke Token

1. Find token in list
2. Click Revoke
3. Confirm revocation

Token is immediately invalidated.

Rotate Token

1. Create new token with same scopes
2. Update your applications
3. Revoke old token

Authentication Errors

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

Causes:

• Missing Authorization header
• Invalid token
• Expired token
• Revoked token

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Token does not have required scope"
  }
}

Causes:

• Token lacks required scope
• Resource access not permitted

OAuth 2.0 (Coming Soon)

Future support for OAuth 2.0 flows:

• Authorization Code
• Client Credentials
• Refresh Tokens

---

Next: Learn about the Projects API