Onboarding flow

Inviting someone through the API creates the user straight away. That is the part worth knowing before you build anything: an invitation is not a pending email with nothing behind it — it provisions a user and associates them with your organization at the moment you send it. So you can finish somebody’s onboarding in one run of your script and they walk into a workspace that is already set up for them.

Inviting requires an API key created by an Owner or an Admin. A key created by a Member cannot invite. See the ceiling rule.

What “pending” means

An invited user exists in three states, and the difference matters when you read them back:

State	`is_active`	`is_pending`	What they can do
Invited	`false`	`true`	Hold groups and grants. Cannot sign in.
Active	`true`	`false`	Everything their role and grants allow.
Deactivated	`false`	`false`	Nothing. Grants are gone.

A pending user is deliberately not active. Anything that counts the people in your organization — seat counts, the billing contact, member lists — leaves them out until they accept. What they can do is receive access, so that the moment they accept, everything is already there.

Because pending is not active, an invitee never appears in a count of your members and is never billed for. Accepting is what moves them.

The flow

Invite

Only email is required. role defaults to member. If you do not know the person’s name yet, leave it out — they will set it themselves when they accept.

curl --request POST \
  --url https://api.nekt.ai/api/v1/invitations/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"email": "analyst@example.com", "role": "member"}'

See Invite User.

Find them as a recipient

The invitee now appears in the recipients endpoints alongside your existing members, which is what makes the next two steps possible.

curl --request GET \
  --url "https://api.nekt.ai/api/v1/permission-recipients/?expand[]=users&search=analyst@example.com" \
  --header "x-api-key: YOUR_API_KEY"

Keep the id from the response — groups and grants both target it.

Grant access

Grants work exactly as they do for an accepted member, on all three axes.You can grant to the invitee directly, or grant to a group — if they are already in one, whatever that group can reach, they can reach.

curl --request POST \
  --url https://api.nekt.ai/api/v1/permissions/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "assignments": [
      {"permission_level": "viewer", "users": ["USER_ID"], "layers": ["LAYER_ID"]}
    ]
  }'

See Permissions flow.

A group is usually the better target. Grant the group once, then put the invitee in it — they inherit everything it holds, and so does the next user you add. Pending invitees can be grouped before they accept, exactly like accepted members. See Add Members.

They accept

The invitation email carries the link. Accepting sets their credential and clears the pending state.No permission is created, moved, or replayed at this point. Everything you granted is already attached to them, which is why acceptance cannot half-fail and leave someone with the wrong access.

Onboard someone end to end

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.nekt.ai"
EMAIL = "analyst@example.com"
GOLD_LAYER = "e4d5c6b7-a8b9-40c1-d2e3-f4a5b6c7d8e9"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

requests.post(
    f"{BASE_URL}/api/v1/invitations/",
    headers=headers,
    json={"email": EMAIL, "role": "member"},
).raise_for_status()

# The invitee is a recipient from this moment on, so the id is available immediately.
recipients = requests.get(
    f"{BASE_URL}/api/v1/permission-recipients/",
    headers=headers,
    params={"expand": "users", "search": EMAIL},
).json()
user_id = recipients["users"][0]["id"]

requests.post(
    f"{BASE_URL}/api/v1/permissions/",
    headers=headers,
    json={
        "assignments": [
            {"permission_level": "viewer", "users": [user_id], "layers": [GOLD_LAYER]}
        ]
    },
).raise_for_status()

Things worth knowing before you build

Only Members appear as permission recipients. Invite someone as admin or owner and they will not show up in the recipients endpoints — not because the invitation failed, but because Owners and Admins bypass data-level permissions entirely, so there is nothing to grant them. Invite as member when you intend to grant. Expiry does not revoke. The email link expires after seven days; the access does not. Resending re-opens the link and keeps every group and grant already attached, so you never re-grant on a resend. Revoking is destructive. It removes every grant on all three axes, and every group membership — and deletes the user if this was their only pending invitation. It is not the same as letting an invitation lapse. See Revoke an Invitation. Someone who already has a Nekt account keeps it. Inviting an existing user to a second organization adds a membership; it does not create a second user or touch their name or password.

Invite User — including resending and changing the role.
List Invitations — the outstanding ones.
Revoke an Invitation — and what it takes back.
Permissions flow — the three grant axes.
Members — what each role can do, in the app.

Platform API

Activities

Connectors

Sources

MCP connections

Connector validations

Transformations

Destinations

Runs

Catalog

Semantic Layer

MCP Tokens

Users

Invitations

Permissions

Visualizations

Tags

API Tokens

Token Access Logs

Onboarding flow

What “pending” means

The flow

Onboard someone end to end

Things worth knowing before you build

​What “pending” means

​The flow

​Onboard someone end to end

​Things worth knowing before you build

​Related

What “pending” means

The flow

Onboard someone end to end

Things worth knowing before you build

Related