Security
The security API allows you to manage a registrar's users, the groups to associate with them, and the IP addresses allowed to access a given service. All methods require the security scope to be present in the token.
Users management
You can get the data of all users or a specific Registrar user, retrieve data of your authenticated user, and create or delete a user.
Regarding user and group associations, you can get the data of groups associated with a specific user or the authenticated user, as well as get the password requirements for a user.
Create a user
POST https://api.nic.it/v1/users
The Registrar can create a user as in the following example:
curl -X POST "https://api.nic.it/v1/users" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
"username" : "giulio.cesare",
"name" : "Giulio",
"lastName" : "Cesare",
"email" : "giulio.ceare@test-giulio-cesare.it",
"password" : "Abcdef-123"
}`
Info
Upon first login, the new user will be asked to confirm their information, verify their email address and change their password.
Get a user by id
GET https://api.nic.it/v1/users/{userId}
You can get the user data by id as in the following example:
Get the authenticated user data
GET https://api.nic.it/v1/user
Each authenticated user can get their user data as in the following example:
Delete a user by id
DELETE https://api.nic.it/v1/users/{userId}
You can delete a user by id as in the following example:
Info
You can delete all users except the main user TAG-REG.
Search for users
GET https://api.nic.it/v1/users
You can search for users belonging to the Registrar using multiple search parameters and operators (advanced search.
Below is the list of parameters and operators available for searching for users:
| Parameter | Type | Cardinality | Supported operators | Default Operator |
|---|---|---|---|---|
| username | String | Single | eq, ne, in, notIn | eq |
| name | String | Single | eq, ne, in, notIn, contains, startsWith, endsWith | eq |
| lastName | String | Single | eq, ne, in, notIn, contains, startsWith, endsWith | eq |
| String | Single | eq, ne, in, notIn | eq | |
| group | String | Single | - | - |
| created | DateTime | Multiple | eq, ne, in, notIn, ge, gt, le, lt, between | eq |
| lastupdate | DateTime | Multiple | eq, ne, in, notIn, ge, gt, le, lt, between | eq |
| lastPasswordChange | DateTime | Multiple | eq, ne, in, notIn, ge, gt, le, lt, between | eq |
Example of searching for Registrar users created since 2024 and belonging to the domain group:
GET /v1/users?created=ge%3A2024-01-01&group=domain HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements" : [ {
"id" : 5,
"username" : "alessandro.magno",
"name" : "Alessandro",
"lastName" : "Magno",
"email" : "alessandro.magno@nic.it",
"created" : "2024-02-05T10:25:03+02:00",
"lastupdate" : "2024-03-05T08:25:02+02:00",
"lastPasswordChange" : "2024-03-05T08:25:02+02:00"
}, {
"id" : 6,
"username" : "giulio.cesare",
"name" : "Giulio",
"lastName" : "Cesare",
"email" : "giulio.cesare@nic.it",
"created" : "2024-03-05T10:25:03+02:00",
"lastupdate" : "2024-04-05T08:25:02+02:00",
"lastPasswordChange" : "2024-04-05T08:25:02+02:00"
} ],
"page" : {
"number" : 0,
"size" : 20,
"totalElements" : 2,
"totalPages" : 1
}
}
curl "https://api.nic.it/v1/users?created=ge:2024-01-01&group=domain" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."
{
"elements" : [ {
"id" : 5,
"username" : "alessandro.magno",
"name" : "Alessandro",
"lastName" : "Magno",
"email" : "alessandro.magno@nic.it",
"created" : "2024-02-05T10:25:03+02:00",
"lastupdate" : "2024-03-05T08:25:02+02:00",
"lastPasswordChange" : "2024-03-05T08:25:02+02:00"
}, {
"id" : 6,
"username" : "giulio.cesare",
"name" : "Giulio",
"lastName" : "Cesare",
"email" : "giulio.cesare@nic.it",
"created" : "2024-03-05T10:25:03+02:00",
"lastupdate" : "2024-04-05T08:25:02+02:00",
"lastPasswordChange" : "2024-04-05T08:25:02+02:00"
} ],
"page" : {
"number" : 0,
"size" : 20,
"totalElements" : 2,
"totalPages" : 1
}
}
http https://api.nic.it/v1/users \
"Authorization: Bearer token..." \
created==ge:2024-01-01 group==domain
{
"elements" : [ {
"id" : 5,
"username" : "alessandro.magno",
"name" : "Alessandro",
"lastName" : "Magno",
"email" : "alessandro.magno@nic.it",
"created" : "2024-02-05T10:25:03+02:00",
"lastupdate" : "2024-03-05T08:25:02+02:00",
"lastPasswordChange" : "2024-03-05T08:25:02+02:00"
}, {
"id" : 6,
"username" : "giulio.cesare",
"name" : "Giulio",
"lastName" : "Cesare",
"email" : "giulio.cesare@nic.it",
"created" : "2024-03-05T10:25:03+02:00",
"lastupdate" : "2024-04-05T08:25:02+02:00",
"lastPasswordChange" : "2024-04-05T08:25:02+02:00"
} ],
"page" : {
"number" : 0,
"size" : 20,
"totalElements" : 2,
"totalPages" : 1
}
}
The search results are paginated.
Info
If no search parameter is specified, all Registrar users will be reported
Get a user's groups
GET https://api.nic.it/v1/users/{userId}/groups
You can get the groups a user belongs to as in the following example:
Modify a user's groups
PUT https://api.nic.it/v1/users/{userId}/groups
You can modify the groups a user belongs to as in the following example:
Info
You are not allowed to modify the groups of the main user TAG-REG.
Get authenticated user groups
GET https://api.nic.it/v1/user/groups
An authenticated user can get the groups they belong to as in the following example:
Password requirements
GET https://api.nic.it/v1/passwordRequirements
Passwords must meet specific requirements, which can be obtained as in the following example:
IP address management
IP address management allows the Registrar to add/enable their IP addresses for access to the following services: - epp-server - das
You can get the list of IP addresses associated with a specific service, add or delete an IP address.
IP addresses for the epp-server service can be associated to all users belonging to the epp group, while for the das service, IP addresses can only be added to the Registrar's main user TAG-REG.
Info
At present, only IPv4 addresses can be specified for both of the above services
Warning
Adding or deleting an IP address is not immediately reflected in the .it Registry's systems and may take several minutes to take effect.
Adding an IP address
POST https://api.nic.it/v1/ipAddresses
You can add an IP address for a service as in the following example:
The response contains all IP addresses for the service to which the address was added, so in the example above it reports the IP addresses of the epp-server service.
Deleting an IP address
DELETE https://api.nic.it/v1/ipAddresses/{ipAddressId}
You can delete an IP address by id as in the following example:
IP address list
GET https://api.nic.it/v1/ipAddresses
You can get the list of IP addresses of a service as in the following example:
GET /v1/ipAddresses?service=epp-server HTTP/1.1
Accept: application/json
Host: api.nic.it
Authentication: Bearer token....
HTTP/1.1 200 OK
Content-Type: application/json
[ {
"id" : 4,
"userId" : 2,
"service" : "epp-server",
"ipAddress" : "192.12.192.3",
"ipVersion" : "IPv4",
"created" : "2023-09-23T17:21:15+02:00"
}, {
"id" : 5,
"userId" : 2,
"service" : "epp-server",
"ipAddress" : "192.12.192.5",
"ipVersion" : "IPv4",
"created" : "2020-08-01T16:10:11+02:00"
} ]
In addition to the mandatory service parameter, you can also specify the following two optional search parameters:
- userId: user id to which the IP address belongs
- ipAddress: IP address