Many customers, one login, nothing shared

Why separate organizations

Two customers can both use 10.0.0.0/16, and usually do. If they shared one organization, every list would show that block twice with nothing but a label to tell them apart, and “the next free /24” would have no single answer. So each customer is its own organization, exactly as if they had signed up themselves, and you work on one customer at a time.

A customer organization can only be one level below yours. A customer cannot have customers of its own.

Add a customer

A new customer. Create the organization yourself. It starts empty, with no members or keys, and is linked to you straight away at the ceiling you choose.

curl -X POST https://nxip.dev/v1/organizations/children \
  -H "x-api-key: $NXIP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Ltd", "roleCeiling": "MEMBER" }'

An organization that already exists. Ask the customer for their organization ID (their admin finds it in GET /v1/organizations/usage), then create a link invite for that organization and send them the token. Only the organization you name can use it, so a token that ends up in the wrong hands is useless. The token is shown once and expires after 7 days.

curl -X POST https://nxip.dev/v1/organizations/link-invites \
  -H "x-api-key: $NXIP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customerOrganizationId": "<their organization id>", "roleCeiling": "READ_ONLY" }'

Their admin can check who the invite is from and what ceiling they would be agreeing to, without accepting it:

curl -X POST https://nxip.dev/v1/organizations/link-invites/inspect \
  -H "x-api-key: $CUSTOMER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "<token>" }'

Then accept it with the same body at /v1/organizations/link-invites/accept.

Work on a customer’s behalf

Use your own key, and name the customer in the x-nxip-organization header. The request then runs inside that customer’s organization, with your role capped at the link’s ceiling.

curl -X POST https://nxip.dev/v1/pools \
  -H "x-api-key: $NXIP_ADMIN_KEY" \
  -H "x-nxip-organization: <customer organization id>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-prod", "cidr": "10.0.0.0/16", "family": "IPV4",
        "environment": "production", "region": "eu-west-2" }'

The header works on pools, subnets (including previews), addresses, lookup, search, usage, members, invites and the activity log. On any other endpoint, such as API keys or billing, a header naming another organization is refused with 400, so a script can never quietly run against the wrong place.

Naming any organization that is not one of your customers returns 404, the same response as an organization that does not exist.

Role ceilings

A Member key acting for a customer with an Admin ceiling is still a Member. An Admin key acting for a customer with a Read-only ceiling can only read.

You can lower a ceiling at any time with PATCH /v1/organizations/children/:id, and it applies to the next request. You cannot raise one on your own: send a new link invite at the higher ceiling, and when the customer’s admin accepts it, the ceiling is replaced.

What the customer sees and controls

• See which provider it is linked to, and at what ceiling.
• See every change the provider made for it, in its own activity log, labelled with the provider.
• See which of its members were invited by the provider, and remove any member.
• End the link at any time. The provider loses access on its very next request. Nothing is deleted.

People you invite into a customer while acting for it become real members of that customer. They stay if the link ends, and the customer’s admin can remove them.

Plans and limits

Having customer organizations needs the Enterprise plan, and a provider can have up to 50 of them (contact us to raise that). A linked customer gets the higher of its own plan’s limits and yours, so linking never makes a customer’s limits worse. If a customer unlinks, it goes back to its own plan’s limits and keeps all of its data.

Endpoints