User Management API

All endpoints require admin access and are scoped to an organization instance.

RegionUS1AP1

Instance ID

API Key

You can find your Instance ID and API Key on the API Keys settings page.

Fill in your region, instance ID, and API key above. The URLs and curl commands below will update automatically.

---

List Users

Returns all users in the organization.

GEThttps://us1.oodle.ai/v1/api/instance/{instance}/users

Name	Type	Description
query	string	Optional. Filter users by email or name (case-insensitive substring match).

Response: 200 OK

{
  "users": [
    {
      "user_id": "auth0|abc123",
      "email": "[email protected]",
      "name": "Alice",
      "picture": "https://..."
    }
  ]
}

curl:

curl -s -X GET \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users' \
  -H 'x-api-key: your-api-key'

---

Send Invitation

Send a single invitation to join the organization.

POSThttps://us1.oodle.ai/v1/api/instance/{instance}/users/invitations

Request body:

Field	Type	Required	Description
email	string	Yes	Invitee email address. Must match an existing member domain.
roles	string[]	Yes	Roles to assign: Admin, Editor, Viewer, Data Ingestion.
sender_email	string	Yes	Email of the org member sending the invite.

Response: 200 OK

{
  "id": "uinv_ABC123",
  "email": "[email protected]",
  "inviter": "Alice",
  "roles": ["Admin"],
  "expires_at": "2026-03-22T00:00:00Z",
  "created_at": "2026-02-20T00:00:00Z"
}

Requirements:

• The invitee's email domain must match the domain of an existing user in the organization. For example, if all current users have @acme.com emails, you can only invite @acme.com addresses.
• sender_email must belong to a current member of the organization.
• You cannot invite yourself.

Errors:

Code	Reason
400	Missing/invalid field, self-invite, domain mismatch, sender not an org member.

curl:

curl -s -X POST \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users/invitations' \
  -H 'x-api-key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "roles": ["Admin"],
  "sender_email": "[email protected]"
}'

---

Bulk Send Invitations

Send multiple invitations in a single request. Each invitation is processed sequentially; per-item results are returned so that partial failures do not abort the batch.

POSThttps://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/bulk

Request body:

Field	Type	Required	Description
sender_email	string	Yes	Email of the org member sending the invites.
invitations	object[]	Yes	Array of invitations (max 100).
invitations[].email	string	Yes	Invitee email address.
invitations[].roles	string[]	Yes	Roles to assign.

Response: 200 OK

Each item in items corresponds positionally to the input array. Failed items include an error string; successful items include an invitation object.

{
  "items": [
    {
      "email": "[email protected]",
      "invitation": {
        "id": "uinv_ABC123",
        "email": "[email protected]",
        "inviter": "Alice",
        "roles": ["Admin"],
        "expires_at": "2026-03-22T00:00:00Z",
        "created_at": "2026-02-20T00:00:00Z"
      }
    },
    {
      "email": "[email protected]",
      "error": "domain does not match existing member domains"
    }
  ]
}

Requirements:

• Maximum 100 invitations per request.
• Each invitee's email domain must match the domain of an existing user in the organization.
• sender_email must belong to a current member of the organization.
• You cannot include your own email in the invitations.

Errors:

Code	Reason
400	Missing sender, empty invitations, exceeds 100 limit, per-item validation.

curl:

curl -s -X POST \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/bulk' \
  -H 'x-api-key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
  "sender_email": "[email protected]",
  "invitations": [
    { "email": "[email protected]", "roles": ["Admin"] },
    { "email": "[email protected]", "roles": ["Viewer"] }
  ]
}'

---

List Invitations

Returns all pending invitations for the organization.

GEThttps://us1.oodle.ai/v1/api/instance/{instance}/users/invitations

Name	Type	Description
query	string	Optional. Filter invitations by email (case-insensitive substring match).

Response: 200 OK

{
  "invitations": [
    {
      "id": "uinv_ABC123",
      "email": "[email protected]",
      "inviter": "Alice",
      "roles": ["Admin"],
      "expires_at": "2026-03-22T00:00:00Z",
      "created_at": "2026-02-20T00:00:00Z"
    }
  ]
}

curl:

curl -s -X GET \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users/invitations' \
  -H 'x-api-key: your-api-key'

---

Get Invitation

Fetch a single invitation by ID.

GEThttps://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/{invitationId}

Response: 200 OK

{
  "id": "uinv_ABC123",
  "email": "[email protected]",
  "inviter": "Alice",
  "roles": ["Admin"],
  "expires_at": "2026-03-22T00:00:00Z",
  "created_at": "2026-02-20T00:00:00Z"
}

Errors:

Code	Reason
400	Invalid invitation ID format.
404	Invitation not found.

curl:

curl -s -X GET \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/{invitationId}' \
  -H 'x-api-key: your-api-key'

---

Delete Invitation

Delete a pending invitation.

DELETEhttps://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/{invitationId}

Response: 200 OK

Errors:

Code	Reason
400	Invalid invitation ID format.
404	Invitation not found.

curl:

curl -s -X DELETE \
  'https://us1.oodle.ai/v1/api/instance/{instance}/users/invitations/{invitationId}' \
  -H 'x-api-key: your-api-key'

---

Common Error Response

All error responses follow this format:

{
  "errors": [
    {
      "message": "description of what went wrong",
      "code": "400"
    }
  ]
}

Authorization

All User Management API endpoints require an Admin role API key. Requests made with non-admin keys will be rejected.