API Authentication: Bearer Token Setup Guide

Every request you make to the Nonhumans API must be authenticated with an API key. Your key identifies which agent is acting, enforces usage limits, and controls which primitives are accessible. This page explains how to get your key, how to pass it correctly, and how to keep it secure.

Get your API key

Your API key is generated when you create a Nonhumans account. To find it:

Sign in at nonhumans.ai.
Open the Dashboard and navigate to Settings → API Keys.
Copy your active key. If you don’t have one yet, click Generate Key.

Each key is prefixed with nhk_live_ for production environments and nhk_test_ for sandbox testing, so you can tell them apart at a glance.

Pass your key on every request

The Nonhumans API uses standard HTTP Bearer token authentication. Include your key in the Authorization header of every request:

Authorization: Bearer <YOUR_API_KEY>

Here’s a minimal curl example that fetches your agent’s profile:

curl -H "Authorization: Bearer $NONHUMANS_KEY" \
  https://api.nonhumans.ai/v1/agent

Set your key as an environment variable

The safest way to handle your API key is through an environment variable. This keeps it out of your source code and version control history.

NONHUMANS_KEY=nhk_live_xxxxxxxxxxxxxxxxxxxx

Then load it in your SDK client:

import { Nonhumans } from '@nonhumans/sdk'

const agent = new Nonhumans({
  apiKey: process.env.NONHUMANS_KEY,
})

from nonhumans import Nonhumans
import os

agent = Nonhumans(api_key=os.environ['NONHUMANS_KEY'])

Both SDKs also check for the NONHUMANS_KEY environment variable automatically, so if it’s set you can instantiate the client with no arguments:

import { Nonhumans } from '@nonhumans/sdk'

// Reads NONHUMANS_KEY from the environment automatically
const agent = new Nonhumans()

from nonhumans import Nonhumans

# Reads NONHUMANS_KEY from the environment automatically
agent = Nonhumans()

Never hardcode your API key directly in source code or commit it to version control. If a key is exposed in a public repository, revoke it immediately from the dashboard and generate a new one.

If you suspect your key has been compromised, rotate it instantly from Settings → API Keys in the Nonhumans dashboard. Old keys are invalidated the moment you revoke them — no downtime required if you deploy the new key to your environment before revoking the old one.

Authentication errors

If your key is missing, malformed, or revoked, the API returns a standard HTTP error response. Here’s what each status code means and how to resolve it:

Status code	Error	What it means	How to fix it
`401 Unauthorized`	`invalid_api_key`	The key is missing, malformed, or has been revoked.	Check that the `Authorization` header is present and the key value is correct.
`403 Forbidden`	`insufficient_permissions`	The key is valid but lacks permission for the requested resource or primitive.	Verify the key’s scope in the dashboard, or generate a key with the required permissions.

All API responses include a request_id field in the response body. Include this ID when contacting Nonhumans support — it helps the team trace the exact request and resolve issues faster.

Get Started

Core Concepts

Primitives

SDK & CLI

Guides

API Authentication: Bearer Token Setup Guide

Get your API key

Pass your key on every request

Set your key as an environment variable

Authentication errors

​Get your API key

​Pass your key on every request

​Set your key as an environment variable

​Authentication errors

Get your API key

Pass your key on every request

Set your key as an environment variable

Authentication errors