Invite an internal user
/internal-usersInvites an internal user to the platform organisation (201, Location). Sends the invite email unless sso_id is set, which makes the user active. An email held by any user, invite or contact email (case-insensitive) is 422 unique. Service or foreign roles are 422 exists; a super-admin role needs a super-admin caller (403 missing_permission). A token outside the platform organisation gets 422 platform_organisation. roles is a deprecated alias of role_ids. Emits internal_user.created. DELETE /internal-users/{id} undoes it.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
application/json, required · InternalUserCreate
The internal user's email. At most 53 characters, so the sign-in username with its invite suffix fits 64. A user, invite or contact email that holds it, in any case, returns 422
unique.Title, such as Mr, Ms or Dr.
The internal user's first name.
The internal user's last name.
The internal user's single sign-on id. When set, the user is created
activeand no invite email is sent.The internal user's id in your own system.
Ids of the roles to grant: your own organisation's or global roles, never service roles, else 422
existsnamingrole_ids.N. A role carrying the super-admin permission needs a super-admin caller, else 403missing_permission.Deprecated alias of
role_ids, accepted until 2027-06-30 withDeprecationandSunsetheaders.role_idswins when both are sent.
{
"email": "iris.stone@example.com",
"title": "Ms",
"first_name": "Iris",
"last_name": "Stone",
"external_id": "HR-1042",
"role_ids": [
12,
34
]
}Responses
{
"data": {
"id": "6f1c2e8a-1b2c-4d5e-8f90-1a2b3c4d5e6f",
"first_name": "Iris",
"last_name": "Stone",
"title": "Ms",
"email": "iris.stone@example.com",
"status": "pending",
"external_id": "HR-1042",
"sso_id": null,
"invite": null,
"two_factor_enabled": false,
"last_login": null,
"created_at": "2026-06-15T10:30:00Z",
"updated_at": "2026-06-15T10:30:00Z"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/internal-users\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"email": "iris.stone@example.com",
"title": "Ms",
"first_name": "Iris",
"last_name": "Stone",
"external_id": "HR-1042",
"role_ids": [
12,
34
]
}'