API Authentication

The Norrix API supports two authentication methods: session tokens and API keys.

Authentication Methods

1. Session Tokens

For browser-based dashboard access. These are managed automatically via cookies after login.

2. API Keys

For CLI and CI/CD integration. Pass these via the Authorization header.

API Key Authentication

Include the API key in the Authorization header:

Authorization: Bearer nrx_your_api_key

Example (curl)

curl -X GET https://norrix.net/api/build \
  -H "Authorization: Bearer nrx_abc123..."

Example (JavaScript)

const response = await fetch('https://norrix.net/api/build', {
  headers: {
    Authorization: `Bearer ${process.env.NORRIX_API_KEY}`,
    'Content-Type': 'application/json',
  },
});
 
const builds = await response.json();

Creating API Keys

1. Go to Dashboard → Settings → API Keys 
2. Click Create API Key
3. Enter a name
4. Select scopes: build, submit, update
5. Copy the key immediately

See API Keys for details.

Key Scopes

API keys have scopes that limit their permissions:

Admin endpoints (/env, /api-keys, /webhooks) require session authentication or an admin-scoped key.

Error Responses

Missing Authentication

{
  "error": "Unauthorized",
  "message": "No authentication provided"
}

HTTP Status: 401

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}

HTTP Status: 401

Insufficient Permissions

{
  "error": "Forbidden",
  "message": "API key does not have 'build' scope"
}

HTTP Status: 403

Organization Context

API calls are made in the context of an organization.

With API Key

API keys are scoped to the organization they were created in. All operations use that organization.

Specify Organization

Some endpoints accept an orgId parameter to override:

GET /api/build?orgId=org_abc123

Environments

Use different API keys for different environments:

Create separate API keys for each environment.

Security Best Practices

Store Keys Securely

• Use environment variables
• Use CI/CD secrets
• Never commit keys to version control

Rotate Keys

• Rotate keys periodically
• Revoke compromised keys immediately
• Create new keys before revoking old ones

Least Privilege

Create keys with only necessary scopes:

# Build-only key
Scopes: [build]

# Deploy key
Scopes: [submit, update]

Monitor Usage

Check lastUsedAt in the dashboard to:

• Identify unused keys
• Detect suspicious activity