Get access

Get started · 7 / 42

Authentication and API keys

Every Northsun REST and MCP request is authenticated with a tenant-scoped API key. Send it as a bearer token from server-side code; Northsun derives the tenant from the key, so callers never choose a tenant in a request body.

Authorization: Bearer sk_live_...

Keys issued to you begin with sk_live_. A missing header, a non-bearer header, an unsupported prefix, or an unknown key returns 401 unauthorized.

Keep keys on the server

Store the key in your deployment platform's secret manager and expose only the environment-variable name to application code:

export NORTHSUN_API_KEY="..."

Never place a key in browser JavaScript, a mobile bundle, a public repository, a screenshot, an agent prompt, or a support message. Your voice or chat platform should call a server-side webhook that adds the Northsun authorization header.

Verify a key safely

Use a read-only caller lookup with a test phone number already present in your tenant:

curl -i "https://mcp.northsun.ai/v1/caller/%2B15551234567" \
  -H "Authorization: Bearer $NORTHSUN_API_KEY"
  • 200 means the key is valid and the caller exists.
  • 404 means the key is valid but that caller does not exist.
  • 401 means the authorization header or key is invalid.
  • 503 means Northsun could not authenticate a cold key because its authentication dependency was temporarily unavailable; retry with backoff.

The %2B is the URL-encoded + in an E.164 phone number.

MCP uses the same key

The hosted MCP endpoint is https://mcp.northsun.ai/mcp. Configure its HTTP headers with the same bearer token; there is no second MCP credential to provision.

Tenant isolation

The authenticated key establishes the tenant before the request reaches the REST route or MCP tool. Do not pass a tenant_id expecting to switch tenants: the frozen public API derives tenancy from authentication.

Next steps