Authentication

The credentials of each surface, how to create and protect an API key, and how a client connects with OAuth.

Each request to Netzo carries a credential. The credential says who acts and in which organization. Its permissions decide what that person or program can do: see Access.

Credentials

Credential	Who uses it	Surfaces	How it is sent
Session	A signed-in person	App, WebMCP, CLI	The app keeps it. In the CLI: `netzo login`
API key	A program, an agent or a script	API, MCP, CLI	Header `x-api-key: <key>`. In the CLI: variable `NETZO_API_KEY`
OAuth	A client that acts for a person	API, MCP	Header `Authorization: Bearer <token>`. The client gets it itself
Signing secret	Your service, to check a webhook	Webhooks	Netzo signs; you check. See Webhooks
Link	Someone outside your organization	Public links	The link itself, and a code if one is asked

A credential belongs to one organization only. Netzo takes the organization from the credential, never from the request.

API keys

Create a key in Administration → Integrations → API keys.

One role per key. Give each key a role with only what its program or agent needs. A key without a permission does not see that table or that action.
Shown once. Copy the key when you create it. Netzo keeps only its hash and cannot show it again.
Always expires. A key expires after 90 days if you choose no other date, and after 365 days at most. Create the new key before the old one expires.
Revoke at once. Delete a key you no longer use or that leaked: the next request with it fails.
Recorded. Each change made with a key goes in the activity log under its name. See Events.

Keep the key in a secrets manager or an environment variable, never in code or in a file of the repository.

OAuth

A client that supports OAuth, such as an AI assistant with MCP, connects with the server address alone (https://app.netzo.ai/mcp). It finds how to authenticate, opens the Netzo sign-in, and the person approves the access. From then on, the client acts with the permissions of that person. See MCP.

Use	When
OAuth	The agent works for a person and must see only what that person sees
API key	The agent or program works on its own, with its own role, for example an integration or a nightly job

CLI

netzo login opens the browser so you sign in as yourself. With no browser, as in CI, set NETZO_API_KEY. See CLI.

Overview

The seven surfaces of Netzo, who acts on each one, and why all of them offer the same actions with the same permissions.

Errors and limits

What Netzo returns when it refuses a request, how to fix or retry it, and how many requests it accepts.