Guides Reference

Invite a user to your organization

/iam/org-invitations creates an organization invitation for a user in your own organization. Inviting members and listing connections are organization access-and-security operations, so they live under /iam/* (identity & access), not /self/* (your own profile). You send who to invite (email) and the role to grant them. connection_id is optional: omit it and the invitee chooses among your organization's enabled connections when they accept, or provide it to pin one identity connection (IdP) the invitee must use: for example, the Microsoft (waad/Entra) connection to force Entra sign-in. When you want to pin a connection, list the ones you can invite through with GET /iam/connections and pass the id you want.

Before you start

You need a valid access token for a caller who is permitted to invite users to the organization. Build one with either sign-in path first:

The call

Send a POST to /iam/org-invitations with your access token in the Authorization header and the invitation as a JSON body. In the simplest case you send just email and role; the invitee then chooses among your organization's enabled connections when they accept. Pin api-version to protect your integration from future changes:

curl
curl -sS -X POST "https://api.cybersentriq.com/iam/org-invitations?api-version=1.0" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"newuser@example.com","role":"account-admin"}'
TypeScript / Node
const res = await fetch(
  "https://api.cybersentriq.com/iam/org-invitations?api-version=1.0",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "newuser@example.com",
      role: "account-admin",
    }),
  },
);
const invitation = await res.json();
Python
import requests

res = requests.post(
    "https://api.cybersentriq.com/iam/org-invitations",
    params={"api-version": "1.0"},
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "email": "newuser@example.com",
        "role": "account-admin",
    },
)
invitation = res.json()
C#
using System.Net.Http;
using System.Text;

var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://api.cybersentriq.com/iam/org-invitations?api-version=1.0");
req.Headers.Add("Authorization", $"Bearer {accessToken}");
req.Content = new StringContent(
    "{\"email\":\"newuser@example.com\",\"role\":\"account-admin\"}",
    Encoding.UTF8, "application/json");

var res = await http.SendAsync(req);
var invitation = await res.Content.ReadAsStringAsync();
Go
body := strings.NewReader(`{"email":"newuser@example.com","role":"account-admin"}`)
req, _ := http.NewRequest("POST",
    "https://api.cybersentriq.com/iam/org-invitations?api-version=1.0", body)
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer res.Body.Close()
// Decode res.Body into your model.

Pinning a connection

To force the invitee onto a specific identity provider, add connection_id. Its value comes from GET /iam/connections. For example, pin the Microsoft (waad/Entra) connection so the invitee must sign in through Entra:

Shell
curl -sS -X POST "https://api.cybersentriq.com/iam/org-invitations?api-version=1.0" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"newuser@example.com","role":"account-admin","connection_id":"con_abc123"}'

The request body

A JSON object describing the invitation:

  • email (required): the email address of the person to invite.
  • role (required): the role to grant the invited user within the organization. One of two values:
    • account-admin: can manage access and security organization-wide (for example, invite and manage users, and manage connections and security settings across the whole org) and manage their own profile. It is a superset of viewer.
    • viewer: can manage their own profile only (self-service; no organization-wide management).
  • connection_id (optional): the identity connection (IdP) the invitee must use to accept. Omit it to let the invitee choose among your organization's enabled connections when they accept. Provide it to pin one specific connection: for example, the Microsoft (waad/Entra) connection to force Entra sign-in. See Getting a connection_id below.

Getting a connection_id

You only need a connection_id when you want to pin a specific connection; otherwise omit it. Its values are opaque, tenant-specific identifiers, so you discover them rather than guess them. Call GET /iam/connections, which lists the connections available to your organization (scoped to your token), pick the one you want the invitee to use, and pass its id as connection_id:

curl
curl -sS "https://api.cybersentriq.com/iam/connections?api-version=1.0" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
json
{
  "connections": [
    { "id": "con_abc123", "name": "Microsoft", "type": "enterprise", "enabled": true },
    { "id": "con_def456", "name": "Username-Password-Authentication", "type": "database", "enabled": true }
  ]
}

What you get back

A 201 with a JSON body describing the created invitation:

JSON
{ "id": "invitation_abc123", "email": "newuser@example.com" }

Additional fields may be present, and more are added as the invitation surface grows.

Versioning

api-version is a query parameter in major.minor form. Omit it and you get the pinned default, 1.0. Send an unsupported version and the call returns 400 with an api-supported-versions response header listing the versions you can use. Every response carries that header, so you can always see what is available.

Pin api-version in production clients so a new default cannot change your integration's behavior underneath it.

When it fails

  • 400: the request body or the api-version you sent is not valid. Check the api-supported-versions response header for the versions you can use.
  • 401: the access token is missing, invalid or expired. Build a fresh token (see the sign-in guides above) and try again. For how to keep a token alive, see Refreshing tokens.
  • 403: your caller is not permitted to invite users to this organization.

Next