Create organization invitations

POST /organizations/{organization_id}/invitations

Creates or refreshes organization invitations. Currently unavailable in self-hosted ECE.

Path parameters

Body Required

The organization invitations to create or refresh

  • emails array[string] Required

    The email addresses to invite to the organization

  • The date and time when the invitation expires. Defaults to three days from now.

  • The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.

    Additional properties are allowed.

    Hide role_assignments attributes Show role_assignments attributes object
    • platform array[object]

      Assignments for roles with platform scope.

      Hide platform attribute Show platform attribute object
      • role_id string Required

        The ID of the role that is assigned.

    • organization array[object]

      Assignments for roles with organization scope.

      Hide organization attributes Show organization attributes object
      • role_id string Required

        The ID of the role that is assigned.

      • organization_id string Required

        The ID of the organization the role is scoped to.

    • deployment array[object]

      Assignments for roles with deployment scope.

      Hide deployment attributes Show deployment attributes object
      • role_id string Required

        The ID of the role that is assigned.

      • organization_id string Required

        The ID of the organization the role is scoped to.

      • all boolean

        When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

      • deployment_ids array[string]

        The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

      • application_roles array[string]

        If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

    • project object

      Assignments for roles with project scope.

      Additional properties are allowed.

      Hide project attributes Show project attributes object
      • elasticsearch array[object]

        The Elasticsearch project-scoped role assignments to set

        Hide elasticsearch attributes Show elasticsearch attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

      • observability array[object]

        The Observability project-scoped role assignments to set

        Hide observability attributes Show observability attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

      • security array[object]

        The Security project-scoped role assignments to set

        Hide security attributes Show security attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

Responses

  • Organization invitations created successfully

    Hide response attribute Show response attribute object
    • invitations array[object] Required

      The list of organization invitations

      Hide invitations attributes Show invitations attributes object
      • token string Required

        The token used to accept the invitation

      • email string Required

        The email address to invite to the organization

      • created_at string(date-time) Required

        The date and time when the invitation was created

      • expires_at string(date-time) Required

        The date and time when the invitation expires

      • expired boolean Required

        True if the invitation is expired

      • accepted_at string(date-time)

        The date and time when the invitation was accepted

      • organization object Required

        An organization

        Additional properties are allowed.

        Hide organization attributes Show organization attributes object
      • The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.

        Additional properties are allowed.

        Hide role_assignments attributes Show role_assignments attributes object
        • platform array[object]

          Assignments for roles with platform scope.

          Hide platform attribute Show platform attribute object
          • role_id string Required

            The ID of the role that is assigned.

        • organization array[object]

          Assignments for roles with organization scope.

          Hide organization attributes Show organization attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

        • deployment array[object]

          Assignments for roles with deployment scope.

          Hide deployment attributes Show deployment attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

          • deployment_ids array[string]

            The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

        • project object

          Assignments for roles with project scope.

          Additional properties are allowed.

          Hide project attributes Show project attributes object
          • elasticsearch array[object]

            The Elasticsearch project-scoped role assignments to set

            Hide elasticsearch attributes Show elasticsearch attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

          • observability array[object]

            The Observability project-scoped role assignments to set

            Hide observability attributes Show observability attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

          • security array[object]

            The Security project-scoped role assignments to set

            Hide security attributes Show security attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

    • Invitation email was not valid. (code: organization.invitation_invalid_email)
    • Invitation already sent. (code: organization.invitation_already_exists)
    • User already belongs to organization. (code: organization.user_organization_already_belongs)
    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Values are organization.invitation_invalid_email, organization.invitation_already_exists, or organization.user_organization_already_belongs.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user authentication is not valid. (code: root.invalid_authentication)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is root.invalid_authentication.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

    • Organization not found. (code: organization.not_found)
    • User not found. (code: user.not_found)
    • Invitation sender does not belong to organization. (code: organization.user_organization_does_not_belong)
    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Values are organization.not_found, user.not_found, or organization.user_organization_does_not_belong.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Request exceeds organization invitation creation rate limits. (code: organization.invitations_rate_limit_exceeded)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invitations_rate_limit_exceeded.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

POST /organizations/{organization_id}/invitations
curl \
 -X POST https://api.elastic-cloud.com/api/v1/organizations/{organization_id}/invitations \
 -d '{"emails":["string"],"expires_in":"string","role_assignments":{"platform":[{"role_id":"string"}],"organization":[{"role_id":"string","organization_id":"string"}],"deployment":[{"role_id":"string","organization_id":"string","all":true,"deployment_ids":["string"],"application_roles":["string"]}],"project":{"elasticsearch":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"observability":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"security":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}]}}}'
Request examples
{
  "emails": [
    "string"
  ],
  "expires_in": "string",
  "role_assignments": {
    "platform": [
      {
        "role_id": "string"
      }
    ],
    "organization": [
      {
        "role_id": "string",
        "organization_id": "string"
      }
    ],
    "deployment": [
      {
        "role_id": "string",
        "organization_id": "string",
        "all": true,
        "deployment_ids": [
          "string"
        ],
        "application_roles": [
          "string"
        ]
      }
    ],
    "project": {
      "elasticsearch": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "observability": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ],
      "security": [
        {
          "role_id": "string",
          "organization_id": "string",
          "all": true,
          "project_ids": [
            "string"
          ],
          "application_roles": [
            "string"
          ]
        }
      ]
    }
  }
}
Response examples (201)
{
  "invitations": [
    {
      "token": "string",
      "email": "string",
      "created_at": "2024-05-04T09:42:00+00:00",
      "expires_at": "2024-05-04T09:42:00+00:00",
      "expired": true,
      "accepted_at": "2024-05-04T09:42:00+00:00",
      "organization": {
        "id": "string",
        "name": "string",
        "default_disk_usage_alerts_enabled": true,
        "notifications_allowed_email_domains": [
          "string"
        ],
        "billing_contacts": [
          "string"
        ],
        "operational_contacts": [
          "string"
        ],
        "sso_login_identifier": "string"
      },
      "role_assignments": {
        "platform": [
          {
            "role_id": "string"
          }
        ],
        "organization": [
          {
            "role_id": "string",
            "organization_id": "string"
          }
        ],
        "deployment": [
          {
            "role_id": "string",
            "organization_id": "string",
            "all": true,
            "deployment_ids": [
              "string"
            ],
            "application_roles": [
              "string"
            ]
          }
        ],
        "project": {
          "elasticsearch": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ],
          "observability": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ],
          "security": [
            {
              "role_id": "string",
              "organization_id": "string",
              "all": true,
              "project_ids": [
                "string"
              ],
              "application_roles": [
                "string"
              ]
            }
          ]
        }
      }
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: organization.invitation_invalid_email

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: root.invalid_authentication

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (429)
# Headers
x-cloud-error-codes: organization.invitations_rate_limit_exceeded

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}