These endpoints are used by the admin interface to manage users. All endpoints require admin authentication.
Create User
POST /user
Create a new user account.
Request Body
{
"name": "John Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900123",
"password": "SecurePassword123!",
"auth_type": "sms_auth"
}
Response
{
"data": {
"id": "user-uuid",
"name": "John Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900123",
"state": "pending",
"auth_type": "sms_auth",
"created_at": "2023-01-01T00:00:00Z"
}
}
201 Created
Get User by ID
GET /user/{user_id}
Retrieve a user’s details.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
{
"data": {
"id": "user-uuid",
"name": "John Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900123",
"state": "active",
"auth_type": "sms_auth",
"email_access_validated_at": "2023-01-01T00:00:00Z",
"logged_in_at": "2023-01-01T12:00:00Z",
"failed_login_count": 0
}
}
Update User Attribute
POST /user/{user_id}
Update user attributes such as name, email, or mobile number.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"name": "John A. Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900456",
"updated_by": "admin-user-uuid"
}
Response
{
"data": {
"id": "user-uuid",
"name": "John A. Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900456"
}
}
When updated_by is provided and email or mobile number is changed, the user will receive a notification about the change.
Archive User
POST /user/{user_id}/archive
Archive a user account. The user will no longer be able to log in.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
Status Code: 204 No Content
Activate User
POST /user/{user_id}/activate
Activate a previously archived user account.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
{
"data": {
"id": "user-uuid",
"state": "active"
}
}
Get User by Email
POST /user/email
Find a user by email address.
Request Body
Response
{
"data": {
"id": "user-uuid",
"name": "John Smith",
"email_address": "[email protected]",
"mobile_number": "+447700900123",
"state": "active"
}
}
Find Users by Email
POST /user/find-users-by-email
Search for users by partial email match.
Request Body
{
"email": "john.smith"
}
Response
{
"data": [
{
"id": "user-uuid-1",
"name": "John Smith",
"email_address": "[email protected]"
},
{
"id": "user-uuid-2",
"name": "John Smith Jr",
"email_address": "[email protected]"
}
]
}
Authentication & Security
Verify Password
POST /user/{user_id}/verify/password
Verify a user’s password.
Request Body
{
"password": "UserPassword123!"
}
Response
Status Code: 204 No Content if password is correct
Status Code: 400 Bad Request if password is incorrect
{
"result": "error",
"message": {"password": ["Incorrect password"]}
}
Send 2FA Code (SMS)
POST /user/{user_id}/sms-code
Send a two-factor authentication code via SMS.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"to": "+447700900123"
}
Response
Status Code: 204 No Content
Send 2FA Code (Email)
POST /user/{user_id}/email-code
Send a two-factor authentication code via email.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"email_auth_link_host": "https://notify.gov.uk",
"next": "/services"
}
Response
Status Code: 204 No Content
Verify 2FA Code
POST /user/{user_id}/verify/code
Verify a two-factor authentication code.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"code": "123456",
"code_type": "sms"
}
Response
Status Code: 204 No Content if code is valid
Status Code: 400 Bad Request if code is expired or invalid
Status Code: 404 Not Found if code not found
Complete WebAuthn Login
POST /user/{user_id}/complete/webauthn-login
Complete login after WebAuthn authentication attempt.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"successful": true,
"webauthn_credential_id": "credential-uuid"
}
Response
Status Code: 204 No Content
Reset Failed Login Count
POST /user/{user_id}/reset-failed-login-count
Reset the failed login count for a user.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
{
"data": {
"id": "user-uuid",
"failed_login_count": 0
}
}
Password Management
Send Password Reset Email
POST /user/reset-password
Send a password reset email to a user.
Request Body
{
"email": "[email protected]",
"admin_base_url": "https://notify.gov.uk",
"next": "/services"
}
Response
Status Code: 204 No Content
Update Password
POST /user/{user_id}/update-password
Update a user’s password.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"_password": "NewSecurePassword123!"
}
Response
{
"data": {
"id": "user-uuid",
"name": "John Smith"
}
}
Email Verification
Send New User Email Verification
POST /user/{user_id}/email-verification
Send an email verification link to a new user.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
{
"admin_base_url": "https://notify.gov.uk"
}
Response
Status Code: 204 No Content
Send Email Change Verification
POST /user/{user_id}/change-email-verification
Send a verification email when a user changes their email address.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
Response
Status Code: 204 No Content
Send Already Registered Email
POST /user/{user_id}/email-already-registered
Send an email notifying that an email address is already registered.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Request Body
Response
Status Code: 204 No Content
Service Permissions
Set User Permissions for Service
POST /user/{user_id}/service/{service_id}/permission
Set a user’s permissions for a specific service.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
service_id | uuid | The service ID |
Request Body
{
"permissions": [
{"permission": "send_messages"},
{"permission": "manage_templates"},
{"permission": "manage_users"}
],
"folder_permissions": ["folder-uuid-1", "folder-uuid-2"]
}
Response
Status Code: 204 No Content
Set User Permissions for Organisation
POST /user/{user_id}/organisation/{organisation_id}/permissions
Set a user’s permissions for an organisation.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
organisation_id | uuid | The organisation ID |
Request Body
{
"permissions": [
{"permission": "manage_services"},
{"permission": "view_all_services"}
]
}
Response
Status Code: 204 No Content
Get Organisations and Services
GET /user/{user_id}/organisations-and-services
Get all organisations and services associated with a user.
Path Parameters
| Parameter | Type | Description |
|---|
user_id | uuid | The user ID |
Response
{
"organisations": [
{
"id": "org-uuid",
"name": "Cabinet Office",
"count_of_live_services": 5
}
],
"services": [
{
"id": "service-uuid",
"name": "My Service",
"restricted": false,
"organisation": "org-uuid"
}
]
}
Available Permissions
Service permissions:
send_messages - Send notificationsmanage_templates - Create and edit templatesmanage_service - Update service settingsmanage_api_keys - Create and revoke API keysmanage_users - Add and remove team membersview_activity - View notification history
Organisation permissions:
manage_services - Create and manage servicesview_all_services - View all services in the organisationmanage_organisation - Update organisation settings
See also: