Skip to content
NimlesNimlesNimles Docs

Create an invite

POST
/api/tenant/{tenantId}/Invites
curl --request POST \
  --url https://api.nimles.com/identity/api/tenant/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/Invites \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "fields": { "additionalProperty": { "value": "example", "valueType": "example" } }, "accessibility": "example", "email": "hello@example.com", "roleDefinitionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "data": { "additionalProperty": "example" }, "control": { "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "organizationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "resourceGroupId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "instance": "example" } }, "sendEmail": true, "message": "example" }'

Creates a new invite. Generates a secure invite code and sets an expiration date.

The inviter needs the right to write invites and role assignments at the invite’s scope, and must itself hold every action the role grants there (403). The role and the scope’s organization and resource group must be the tenant’s (400). With sendEmail, Identity mails the invite with a link to the accept page configured for the calling client (400 without one), up to a daily limit per tenant (429).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
tenantId
required
string format: uuid

Your tenant id.

Request Body

Section titled “Request Body”

The invite data.

Media typeapplication/json
object
fields
object
key
additional properties
object
value
required
nullable
valueType
string
nullable
accessibility
string
nullable
email
required
string format: email
>= 1 characters <= 254 characters
roleDefinitionId
required
string format: uuid
scope
required
object
data
object
key
additional properties
string
control
required
object
tenantId
string format: uuid
nullable
organizationId
string format: uuid
nullable
resourceGroupId
string format: uuid
nullable
instance
string
nullable
sendEmail
boolean
message
string
nullable <= 500 characters

Example generated

{
  "fields": {
    "additionalProperty": {
      "value": "example",
      "valueType": "example"
    }
  },
  "accessibility": "example",
  "email": "hello@example.com",
  "roleDefinitionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "scope": {
    "data": {
      "additionalProperty": "example"
    },
    "control": {
      "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "organizationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "resourceGroupId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "instance": "example"
    }
  },
  "sendEmail": true,
  "message": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Created. The body is the item, or { data: { id } } when it cannot be read yet. Location is the item’s path within the service, /api/tenant/{tenantId}/{Resource}/{id}, without the /{service} prefix api.nimles.com routes by: use data.id from the body.

Media typeapplication/json
One of:
object
fields
object
key
additional properties
string
data
object
fields
object
key
additional properties
object
value
required
nullable
valueType
string
nullable
accessibility
string
nullable
id
string format: uuid
relations
Array<object>
nullable
object
fields
object
key
additional properties
object
value
required
nullable
valueType
string
nullable
accessibility
string
nullable
id
string format: uuid
name
string
nullable
entityId
required
string format: uuid
entityType
required
string
>= 1 characters
relationType
required
string
>= 1 characters
tenantId
string format: uuid
nullable
resourceGroupId
string format: uuid
nullable
creatorId
string format: uuid
nullable
createdDate
string format: date-time
nullable
version
integer format: int32
nullable
lastModified
string format: date-time
nullable
email
required
string
>= 1 characters
roleDefinitionId
required
string format: uuid
scope
required
object
data
object
key
additional properties
string
control
required
object
tenantId
string format: uuid
nullable
organizationId
string format: uuid
nullable
resourceGroupId
string format: uuid
nullable
instance
string
nullable
status
required
string
>= 1 characters
expiresAt
string format: date-time
nullable
acceptedAt
string format: date-time
nullable
acceptedByPrincipalId
string format: uuid
nullable
inviteCode
string
nullable
requiresApproval
boolean
requestedByPrincipalId
string format: uuid
nullable
requesterName
string
nullable
requesterPhone
string
nullable
requestMessage
string
nullable
allowAnyAccount
boolean
isExpired
boolean
sendEmail
boolean
lastSentAt
string format: date-time
nullable
invitedByName
string
nullable
invitedByEmail
string
nullable
message
string
nullable
roleName
string
nullable
organizationName
string
nullable

Example generated

{
  "data": {
    "fields": {
      "additionalProperty": {
        "value": "example",
        "valueType": "example"
      }
    },
    "accessibility": "example",
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "relations": [
      {
        "fields": {
          "additionalProperty": {
            "value": "example",
            "valueType": "example"
          }
        },
        "accessibility": "example",
        "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "name": "example",
        "entityId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "entityType": "example",
        "relationType": "example"
      }
    ],
    "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "resourceGroupId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "creatorId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "createdDate": "2026-04-15T12:00:00Z",
    "version": 1,
    "lastModified": "2026-04-15T12:00:00Z",
    "email": "example",
    "roleDefinitionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "scope": {
      "data": {
        "additionalProperty": "example"
      },
      "control": {
        "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "organizationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "resourceGroupId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "instance": "example"
      }
    },
    "status": "example",
    "expiresAt": "2026-04-15T12:00:00Z",
    "acceptedAt": "2026-04-15T12:00:00Z",
    "acceptedByPrincipalId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "inviteCode": "example",
    "requiresApproval": true,
    "requestedByPrincipalId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "requesterName": "example",
    "requesterPhone": "example",
    "requestMessage": "example",
    "allowAnyAccount": true,
    "isExpired": true,
    "sendEmail": true,
    "lastSentAt": "2026-04-15T12:00:00Z",
    "invitedByName": "example",
    "invitedByEmail": "example",
    "message": "example",
    "roleName": "example",
    "organizationName": "example"
  }
}

Headers

Section titled “Headers”
Location
string

The new item’s path within the service, without the service prefix: /api/tenant/{tenantId}/{Resource}/{id}.

401

Section titled “401”

Unauthorized: no bearer token, or one that is expired or not for this API.

403

Section titled “403”

Forbidden: the caller holds no role that allows this action at this scope. The body is empty, or a problem whose detail names the action.

Media typeapplication/json

An RFC 9457 problem.

object
detail
string
nullable
instance
string
nullable
status
integer format: int32
nullable
title
string
nullable
type
string
nullable
key
additional properties

Example generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

409

Section titled “409”

Conflict: the item kept changing under concurrent writes; read it again and retry.

Media typeapplication/problem+json

An RFC 9457 problem.

object
detail
string
nullable
instance
string
nullable
status
integer format: int32
nullable
title
string
nullable
type
string
nullable
key
additional properties

Example generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

422

Section titled “422”

Unprocessable: the body or the change is invalid. The errors are keyed by member.

Media typeapplication/problem+json

A validation problem: the messages by member (or by JSON Pointer for a patch).

object
errors
object
key
additional properties
Array<string>
status
integer format: int32
nullable
title
string
nullable
type
string
nullable
key
additional properties

Example generated

{
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "status": 1,
  "title": "example",
  "type": "example"
}