Admin API

You can use the Admin API to manage the people who use your archive: list, create, and update users, reset their password, and send their invitation again. It also lists the roles that you can give to users and the archive profiles that you need when you build an ingest request.

User accounts live in your identity provider, not in the archive. A user that you create with an enabled account gets an invitation email before they can sign in.

Every call needs the headers in Common headers and an access token, as described in Authentication.

To manage users, you need the user-management role and user management rights in your identity provider. To search users and groups, you need archive-content-manager or archive-records-manager instead.

List users

Returns one page of users, with the total number of users so that you can page through them.

GET /v2/user

Required role: user-management

Query parameters:

Headers:

Response: 200 OK with a UserList.

{
  "items": [
    {
      "user": {
        "id": "5c1e8a40-2b7d-4f0e-9a51-3d2c7e6b9f10",
        "username": "jdoe",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "jane.doe@example.com",
        "userRoles": ["Application manager"],
        "enabled": true,
        "emailVerified": true
      }
    }
  ],
  "page": 0,
  "pageSize": 100,
  "total": 1
}

Errors that you can get:

• 400 with reason OUT_OF_RANGE: page is below 0, or pageSize is below 1.

• 400 with reason UNSUPPORTED_VALUE: sortBy isn't one of the four allowed fields.

Create a user

Creates a user account. You can also create a package for the user in the same call.

POST /v2/user

Required role: user-management

Query parameters:

Headers:

Body fields:

{
  "user": {
    "username": "jdoe",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "userRoles": ["Application manager"],
    "enabled": true
  }
}

What to know about the new account:

• The invitation email only goes out if enabled is true. It asks the user to verify their email address, choose a password, and set up two-step verification (TOTP).

• The user's package, with ingestPackage=true, gets its package ID stored on the user as userPackageId. If the archive can't create the package, it deletes the new user again.

Response: 200 OK with the created user (a User) and a sip. Without ingestPackage, sip is null:

{
  "user": {
    "id": "5c1e8a40-2b7d-4f0e-9a51-3d2c7e6b9f10",
    "username": "jdoe",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "userRoles": ["Application manager"],
    "enabled": true,
    "emailVerified": false
  },
  "sip": null
}

With ingestPackage=true, sip describes the submission for the user's package, as in the Ingest API.

Note: The package ingest is asynchronous. A 200 means that the archive accepted the package, not that the ingest succeeded. To follow it up, go to Ingest API.

Errors that you can get:

• 400 with reason REQUIRED_FIELD: ingestPackage is true, but package, package.profile, or package.metadatas is missing.

• 400 with reason INVALID_PACKAGE_ID: package.packageId contains characters that a package ID can't have.

• 404 with reason ROLE_NOT_FOUND: a role in userRoles isn't one that you can assign.

• 409 with reason USER_ALREADY_EXISTS: the identity provider already has a user like this one, for example with the same username.

With ingestPackage=true, the package goes through the same checks as any ingest, such as the metadata validation, and you need permission to add content to the archive. For those errors, go to Ingest API.

Update a user

Replaces a user's details and roles. You can also update the metadata of the user's package in the same call.

PUT /v2/user/{userId}

Required role: user-management

Path parameters:

Query parameters:

Headers:

Body fields:

The update replaces the user, so send every field, not only the ones that change:

• userRoles becomes the user's full list of roles. To keep a role, include it.

• username can't change. Send the user's current username.

To get the current values, list the users first.

The archive updates the user first, and the package after that. If the package update fails, you get an error, but the change to the user stays.

Response: 200 OK with the updated user (a User) and a sip, in the same shape as for Create a user.

Errors that you can get:

• 400 with reason INVALID_VALUE: the username in the body isn't the user's current username.

• 400 with reason REQUIRED_FIELD: ingestPackage is true, but package, package.profile, or package.metadatas is missing.

• 404 with reason USER_NOT_FOUND: there's no user with this ID.

• 404 with reason ROLE_NOT_FOUND: a role in userRoles isn't one that you can assign.

• 404 with reason RESOURCE_NOT_FOUND: with ingestPackage=true, there's no package with package.packageId that you can access.

Reset a user's password

Sends the user an email with a link to choose a new password. You can also make them set up two-step verification again.

PUT /v2/user/{userId}/reset

Required role: user-management

Path parameters:

Query parameters:

Response: 200 OK.

{
  "emailSent": true
}

Errors that you can get:

• 404 with reason USER_NOT_FOUND: there's no user with this ID.

Send the invitation again

Sends the user a new invitation email.

POST /v2/user/{userId}/resend-invite

Required role: user-management

Path parameters:

Query parameters:

Response: 200 OK with {"emailSent": true}, as for Reset a user's password.

Errors that you can get:

• 404 with reason USER_NOT_FOUND: there's no user with this ID.

Search users and groups

Finds the users and groups in your identity provider that match a search term.

GET /v2/user/search

Required role: archive-content-manager or archive-records-manager

Query parameters:

Response: 200 OK with a list of Principal objects: first the users, then the groups.

[
  {
    "id": "5c1e8a40-2b7d-4f0e-9a51-3d2c7e6b9f10",
    "name": "jdoe",
    "displayName": "Jane Doe",
    "type": "USER"
  },
  {
    "id": "a8f3c2d1-6e4b-4c7a-8d9e-1f2a3b4c5d6e",
    "name": "records-team",
    "displayName": "/records-team",
    "type": "GROUP"
  }
]

Errors that you can get:

• 400 with reason OUT_OF_RANGE: search is missing or shorter than 2 characters.

List the roles that you can assign

Returns the roles that you can put in a user's userRoles.

GET /v2/role

Required role: rights to read the roles in your identity provider. The call uses your own access token there.

Response: 200 OK with a list of Role objects.

[
  {
    "name": "Application manager"
  }
]

The list holds the Application manager role and the roles whose name starts with Vault.

List archive profiles

Returns the archive profiles that are enabled in your archive. When you send content to the archive, you pick one of these profiles for the package: put its urn in the profile field of the ingest request. To build the request, go to Ingest API.

GET /v2/profile

Required role: any valid access token.

Response: 200 OK with a list of ArchiveProfile objects.

[
  {
    "urn": "urn:example:profiles:hr-records-1.0",
    "name": "HR records"
  }
]

The ingest request also needs the namespaces of your metadata schemas, for the schema of each item in its metadatas. Docbyte provides them.

Tip: To list the tenants that you can reach, for example to pick the target of a package transfer, go to Archive API.

Schemas

User

The user in requests and responses. In a create request, leave out id and userPackageId.

UserPackage

The package to create or update for a user, with ingestPackage=true. The fields work like the ones in a document ingest request in the Ingest API.

UserList

Principal

Role

ArchiveProfile