io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-rc0003
8. API Access
Previous
8. API Access
Up
8.2. User Protocol
Next

# 8.1. Admin Protocol

- 8.1.1. Versioning
- 8.1.2. Health
- 8.1.3. Version 1.0
  - 8.1.3.1. Encoding
  - 8.1.3.2. Login
  - 8.1.3.3. Commands
  - 8.1.3.4. Generated Documentation
- 8.1.4. Schemas

## 8.1.1. Versioning

1
The Admin API service exposes one or more versions of the Admin protocol. The service uses the verdant protocol to advertise which versions of the Admin protocol are available. Executing a GET request to the root endpoint will yield a verdant message showing which versions of the Admin protocol are available. The Admin protocol is assigned the protocol identifier de1ef9f2-5ea7-388a-9b79-788c132abfd1.
2
As an example, the following shows that the Admin protocol version 1 is available at /admin/1/0/:

### 8.1.1.3. Verdant Example

    $ curl https://idstore.example.com:51000/ | hexdump
    0000:0000 | 00 00 00 01  00 00 00 01  DE 1E F9 F2  5E A7 38 8A | ........Þ.ùò^§8.
    0000:0010 | 9B 79 78 8C  13 2A BF D1  00 00 00 01  00 00 00 00 | .yx..*¿Ñ........
    0000:0020 | 00 00 00 0B  2F 61 64 6D  69 6E 2F 31  2F 30 2F    | ..../admin/1/0/

## 8.1.2. Health

1
The Admin API service exposes a health check endpoint at /health. The endpoint returns a 200 status code and the string OK if the server's most recent internal health checks succeeded. The server returns a 500 status code and string not equal to OK if the server's most recent internal health checks failed. In both cases, the string is returned directly as a text/plain UTF-8 value.

## 8.1.3. Version 1.0

## 8.1.3.1. Encoding

1
The version 1 Admin protocol uses cedarbridge encoded messages over HTTP(s).

## 8.1.3.2. Login

1
Send an IdA1CommandLogin command to /admin/1/0/login. If the login succeeds, a cookie named IDSTORE_ADMIN_API_SESSION will be set. This cookie must be included with all subsequent requests.

## 8.1.3.3. Commands

1
After logging in successfully, send commands of type IdA1Command* to /admin/1/0/command. Failed commands will yield a value of type IdA1ResponseError, whilst successful results will yield values of type IdA1Response*.

## 8.1.3.4. Generated Documentation

1
Generated documentation for the Cedarbridge schemas is available:

### 8.1.3.4.2. Schema Documentation

- com.io7m.cedarbridge
- com.io7m.idstore.protocol.admin.cb

## 8.1.4. Schemas

### 8.1.4.1. Schemas

    ;
    ; Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.io7m.com
    ;
    ; Permission to use, copy, modify, and/or distribute this software for any
    ; purpose with or without fee is hereby granted, provided that the above
    ; copyright notice and this permission notice appear in all copies.
    ;
    ; THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    ; WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    ; MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
    ; SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    ; WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ; ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
    ; IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
    ;

    [language cedarbridge 1 0]

    [package com.io7m.idstore.protocol.admin.cb]

    [import com.io7m.cedarbridge cb]
    [import com.io7m.cedarbridge.time ct]

    [documentation IdA1Password "Information for a hashed password."]
    [record IdA1Password
      [documentation algorithm "The password algorithm."]
      [field algorithm cb:String]
      [documentation hash "The password hash."]
      [field hash cb:String]
      [documentation salt "The password salt."]
      [field salt cb:String]
      [documentation expires "The password expiration date."]
      [field expires [cb:Option ct:OffsetDateTime]]
    ]

    [documentation IdA1TimestampUTC "A UTC timestamp value."]
    [record IdA1TimestampUTC
      [documentation year "The year."]
      [field year cb:IntegerUnsigned32]
      [documentation month "The month in the range [1, 12]."]
      [field month cb:IntegerUnsigned8]
      [documentation day "The day of the month in the range [1, 31]."]
      [field day cb:IntegerUnsigned8]
      [documentation hour "The hour in the range [0, 23]."]
      [field hour cb:IntegerUnsigned8]
      [documentation minute "The minute in the range [0, 59]."]
      [field minute cb:IntegerUnsigned8]
      [documentation second "The second in the range [0, 59]."]
      [field second cb:IntegerUnsigned8]
      [documentation millisecond "The millisecond in the range [0, 999]."]
      [field millisecond cb:IntegerUnsigned32]
    ]

    [documentation IdA1Ban "An account ban."]
    [record IdA1Ban
      [documentation user "The user (or admin) ID."]
      [field user cb:UUID]
      [documentation reason "The ban reason."]
      [field reason cb:String]
      [documentation expires "The expiration date, if any."]
      [field expires [cb:Option IdA1TimestampUTC]]
    ]

    [documentation IdA1TimeRange "A UTC time range."]
    [record IdA1TimeRange
      [documentation lower "The lower bound."]
      [field lower IdA1TimestampUTC]
      [documentation upper "The upper bound."]
      [field upper IdA1TimestampUTC]
    ]

    [documentation IdA1Login "A login record."]
    [record IdA1Login
      [documentation user "The user ID."]
      [field user cb:UUID]
      [documentation time "The login time."]
      [field time IdA1TimestampUTC]
      [documentation host "The user's host."]
      [field host cb:String]
      [documentation agent "The user's agent."]
      [field agent cb:String]
    ]

    [documentation IdA1AdminPermission "An admin permission."]
    [variant IdA1AdminPermission
      [documentation AdminBan "A permission that allows for banning admins."]
      [case AdminBan]
      [documentation AdminCreate "A permission that allows for creating admins."]
      [case AdminCreate]
      [documentation AdminDelete "A permission that allows for deleting admins."]
      [case AdminDelete]
      [documentation AdminWriteCredentials "A permission that allows updating admin credentials."]
      [case AdminWriteCredentials]
      [documentation AdminWriteCredentialsSelf "A permission that allows an admin to update its own credentials."]
      [case AdminWriteCredentialsSelf]
      [documentation AdminWriteEmail "A permission that allows updating admin emails."]
      [case AdminWriteEmail]
      [documentation AdminWriteEmailSelf "A permission that allows an admin to update its own emails."]
      [case AdminWriteEmailSelf]
      [documentation AdminWritePermissions "A permission that allows updating admin permissions."]
      [case AdminWritePermissions]
      [documentation AdminWritePermissionsSelf "A permission that allows an admin to update its own permissions."]
      [case AdminWritePermissionsSelf]
      [documentation AdminRead "A permission that allows reading admins."]
      [case AdminRead]
      [documentation AuditRead "A permission that allows reading the audit log."]
      [case AuditRead]
      [documentation UserDelete "A permission that allows deleting users."]
      [case UserDelete]
      [documentation UserCreate "A permission that allows creating users."]
      [case UserCreate]
      [documentation UserWriteCredentials "A permission that allows updating user credentials."]
      [case UserWriteCredentials]
      [documentation UserWriteEmail "A permission that allows updating user emails."]
      [case UserWriteEmail]
      [documentation UserRead "A permission that allows reading users."]
      [case UserRead]
      [documentation UserBan "A permission that allows for banning users."]
      [case UserBan]
      [documentation MailTest "A permission that allows for sending test mail."]
      [case MailTest]
      [documentation MaintenanceMode "A permission that allows for changing the server's maintenance mode."]
      [case MaintenanceMode]
    ]

    [documentation IdA1AdminColumn "A column to use for sorting admins."]
    [variant IdA1AdminColumn
      [documentation ByID "Order by admin ID."]
      [case ByID]
      [documentation ByIDName "Order by admin id name."]
      [case ByIDName]
      [documentation ByRealName "Order by admin realname."]
      [case ByRealName]
      [documentation ByTimeCreated "Order by admin creation time."]
      [case ByTimeCreated]
      [documentation ByTimeUpdated "Order by admin update time."]
      [case ByTimeUpdated]
    ]

    [documentation IdA1AdminColumnOrdering "A column ordering spec."]
    [record IdA1AdminColumnOrdering
      [documentation column "The admin column."]
      [field column IdA1AdminColumn]
      [documentation ascending "True if the results should be ascending."]
      [field ascending cb:Boolean]
    ]

    [documentation IdA1AdminSearchParameters "Search parameters for admins."]
    [record IdA1AdminSearchParameters
      [documentation timeCreatedRange "The range of creation times for returned admins."]
      [field timeCreatedRange IdA1TimeRange]
      [documentation timeUpdatedRange "The range of update times for returned admins."]
      [field timeUpdatedRange IdA1TimeRange]
      [documentation search "The search query text."]
      [field search [cb:Option cb:String]]
      [documentation ordering "The result ordering."]
      [field ordering IdA1AdminColumnOrdering]
      [documentation limit "The limit on the number of results."]
      [field limit cb:IntegerUnsigned16]
    ]

    [documentation IdA1AdminSearchByEmailParameters "Search parameters for admins (by email)."]
    [record IdA1AdminSearchByEmailParameters
      [documentation timeCreatedRange "The range of creation times for returned admins."]
      [field timeCreatedRange IdA1TimeRange]
      [documentation timeUpdatedRange "The range of update times for returned admins."]
      [field timeUpdatedRange IdA1TimeRange]
      [documentation search "The search query text."]
      [field search cb:String]
      [documentation ordering "The result ordering."]
      [field ordering IdA1AdminColumnOrdering]
      [documentation limit "The limit on the number of results."]
      [field limit cb:IntegerUnsigned16]
    ]

    [documentation IdA1AuditSearchParameters "Search parameters for audit records."]
    [record IdA1AuditSearchParameters
      [documentation timeRange "The range of time to include."]
      [field timeRange IdA1TimeRange]
      [documentation owner "All records contain this owner, if specified."]
      [field owner [cb:Option cb:String]]
      [documentation message "All records contain this message, if specified."]
      [field message [cb:Option cb:String]]
      [documentation type "All records contain this type, if specified."]
      [field type [cb:Option cb:String]]
      [documentation limit "The limit on the number of results."]
      [field limit cb:IntegerUnsigned16]
    ]

    [documentation IdA1UserColumn "A column to use for sorting users."]
    [variant IdA1UserColumn
      [documentation ByID "Order by user ID."]
      [case ByID]
      [documentation ByIDName "Order by user id name."]
      [case ByIDName]
      [documentation ByRealName "Order by user realname."]
      [case ByRealName]
      [documentation ByTimeCreated "Order by user creation time."]
      [case ByTimeCreated]
      [documentation ByTimeUpdated "Order by user update time."]
      [case ByTimeUpdated]
    ]

    [documentation IdA1UserColumnOrdering "A column ordering spec."]
    [record IdA1UserColumnOrdering
      [documentation column "The user column."]
      [field column IdA1UserColumn]
      [documentation ascending "True if the results should be ascending."]
      [field ascending cb:Boolean]
    ]

    [documentation IdA1UserSearchParameters "Search parameters for users."]
    [record IdA1UserSearchParameters
      [documentation timeCreatedRange "The range of creation times for returned users."]
      [field timeCreatedRange IdA1TimeRange]
      [documentation timeUpdatedRange "The range of update times for returned users."]
      [field timeUpdatedRange IdA1TimeRange]
      [documentation search "The search query text."]
      [field search [cb:Option cb:String]]
      [documentation ordering "The result ordering."]
      [field ordering IdA1UserColumnOrdering]
      [documentation limit "The limit on the number of results."]
      [field limit cb:IntegerUnsigned16]
    ]

    [documentation IdA1UserSearchByEmailParameters "Search parameters for users (by email)."]
    [record IdA1UserSearchByEmailParameters
      [documentation timeCreatedRange "The range of creation times for returned users."]
      [field timeCreatedRange IdA1TimeRange]
      [documentation timeUpdatedRange "The range of update times for returned users."]
      [field timeUpdatedRange IdA1TimeRange]
      [documentation search "The search query text."]
      [field search cb:String]
      [documentation ordering "The result ordering."]
      [field ordering IdA1UserColumnOrdering]
      [documentation limit "The limit on the number of results."]
      [field limit cb:IntegerUnsigned16]
    ]

    [documentation IdA1Admin "An administrator."]
    [record IdA1Admin
      [documentation id "The admin ID."]
      [field id cb:UUID]
      [documentation idName "The admin ID name."]
      [field idName cb:String]
      [documentation realName "The admin real name."]
      [field realName cb:String]
      [documentation emails "The admin emails."]
      [field emails [cb:List cb:String]]
      [documentation timeCreated "The time the admin was created."]
      [field timeCreated IdA1TimestampUTC]
      [documentation timeUpdated "The time the admin was last updated."]
      [field timeUpdated IdA1TimestampUTC]
      [documentation password "The hashed admin password."]
      [field password IdA1Password]
      [documentation permissions "The admin permissions."]
      [field permissions [cb:List IdA1AdminPermission]]
    ]

    [documentation IdA1Page "A page of results."]
    [record IdA1Page
      [documentation T "The type of result values."]
      [parameter T]
      [documentation items "The list of results."]
      [field items [cb:List T]]
      [documentation pageIndex "The page index."]
      [field pageIndex cb:IntegerUnsigned32]
      [documentation pageCount "The page count."]
      [field pageCount cb:IntegerUnsigned32]
      [documentation pageFirstOffset "The offset of the first item in the page."]
      [field pageFirstOffset cb:IntegerUnsigned64]]

    [documentation IdA1AdminSummary "An admin summary."]
    [record IdA1AdminSummary
      [documentation id "The admin ID."]
      [field id cb:UUID]
      [documentation idName "The admin ID name."]
      [field idName cb:String]
      [documentation realName "The admin real name."]
      [field realName cb:String]
      [documentation timeCreated "The time the admin was created."]
      [field timeCreated IdA1TimestampUTC]
      [documentation timeUpdated "The time the admin was last updated."]
      [field timeUpdated IdA1TimestampUTC]
    ]

    [documentation IdA1AuditEvent "An audit event."]
    [record IdA1AuditEvent
      [documentation id "The audit event ID."]
      [field id cb:IntegerUnsigned64]
      [documentation owner "The audit event owner."]
      [field owner cb:UUID]
      [documentation time "The audit event time."]
      [field time IdA1TimestampUTC]
      [documentation type "The audit event type."]
      [field type cb:String]
      [documentation message "The audit event message."]
      [field message cb:String]
    ]

    [documentation IdA1User "A user."]
    [record IdA1User
      [documentation id "The user ID."]
      [field id cb:UUID]
      [documentation idName "The user ID name."]
      [field idName cb:String]
      [documentation realName "The user real name."]
      [field realName cb:String]
      [documentation emails "The user emails."]
      [field emails [cb:List cb:String]]
      [documentation timeCreated "The time the user was created."]
      [field timeCreated IdA1TimestampUTC]
      [documentation timeUpdated "The time the user was last updated."]
      [field timeUpdated IdA1TimestampUTC]
      [documentation password "The hashed user password."]
      [field password IdA1Password]
    ]

    [documentation IdA1UserSummary "A user summary."]
    [record IdA1UserSummary
      [documentation id "The user ID."]
      [field id cb:UUID]
      [documentation idName "The user ID name."]
      [field idName cb:String]
      [documentation realName "The user real name."]
      [field realName cb:String]
      [documentation timeCreated "The time the user was created."]
      [field timeCreated IdA1TimestampUTC]
      [documentation timeUpdated "The time the user was last updated."]
      [field timeUpdated IdA1TimestampUTC]
    ]

    [documentation IdA1PasswordExpirationSet "The possible behaviours for setting password expirations."]
    [variant IdA1PasswordExpirationSet
      [documentation Never "Never expire, regardless of the server setting."]
      [case Never]
      [documentation Refresh "Refresh the password to the server setting."]
      [case Refresh]
      [documentation Specific "Expire at the given time, regardless of the server setting."]
      [case Specific [field time ct:OffsetDateTime]]
    ]

    ;
    ; Admin commands.
    ;

    [documentation IdA1CommandAdminBanCreate "Ban an admin."]
    [record IdA1CommandAdminBanCreate
      [documentation ban "The ban."]
      [field ban IdA1Ban]
    ]

    [documentation IdA1CommandAdminBanDelete "Remove a ban on an admin."]
    [record IdA1CommandAdminBanDelete
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
    ]

    [documentation IdA1CommandAdminBanGet "Get a ban on an admin."]
    [record IdA1CommandAdminBanGet
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
    ]

    [documentation IdA1CommandAdminCreate "Create an admin."]
    [record IdA1CommandAdminCreate
      [documentation adminId "The admin."]
      [field adminId [cb:Option cb:UUID]]
      [documentation idName "The admin ID name."]
      [field idName cb:String]
      [documentation realName "The admin real name."]
      [field realName cb:String]
      [documentation email "The admin email."]
      [field email cb:String]
      [documentation password "The admin password."]
      [field password IdA1Password]
      [documentation permissions "The set of permissions."]
      [field permissions [cb:List IdA1AdminPermission]]
    ]

    [documentation IdA1CommandAdminDelete "Delete an admin."]
    [record IdA1CommandAdminDelete
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
    ]

    [documentation IdA1CommandAdminEmailAdd "Add an email address to the given admin."]
    [record IdA1CommandAdminEmailAdd
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandAdminEmailRemove "Remove an email address from the given admin."]
    [record IdA1CommandAdminEmailRemove
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandAdminGet "Get the given admin."]
    [record IdA1CommandAdminGet
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
    ]

    [documentation IdA1CommandAdminGetByEmail "Get the admin with the given email address."]
    [record IdA1CommandAdminGetByEmail
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandAdminPermissionGrant "Grant a permission to the given admin."]
    [record IdA1CommandAdminPermissionGrant
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
      [documentation permission "The permission."]
      [field permission IdA1AdminPermission]
    ]

    [documentation IdA1CommandAdminPermissionRevoke "Revoke a permission from the given admin."]
    [record IdA1CommandAdminPermissionRevoke
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
      [documentation permission "The permission."]
      [field permission IdA1AdminPermission]
    ]

    [documentation IdA1CommandAdminSearchBegin "Start searching for admins."]
    [record IdA1CommandAdminSearchBegin
      [documentation parameters "The search parameters."]
      [field parameters IdA1AdminSearchParameters]
    ]

    [documentation IdA1CommandAdminSearchByEmailBegin "Start searching for admins (by email)."]
    [record IdA1CommandAdminSearchByEmailBegin
      [documentation parameters "The search parameters."]
      [field parameters IdA1AdminSearchByEmailParameters]
    ]

    [documentation IdA1CommandAdminSearchByEmailNext "Get the next page of admin search results."]
    [record IdA1CommandAdminSearchByEmailNext]

    [documentation IdA1CommandAdminSearchByEmailPrevious "Get the previous page of admin search results."]
    [record IdA1CommandAdminSearchByEmailPrevious]

    [documentation IdA1CommandAdminSearchNext "Get the next page of admin search results."]
    [record IdA1CommandAdminSearchNext]

    [documentation IdA1CommandAdminSearchPrevious "Get the previous page of admin search results."]
    [record IdA1CommandAdminSearchPrevious]

    [documentation IdA1CommandAdminSelf "A request to fetch the admin's own profile."]
    [record IdA1CommandAdminSelf]

    [documentation IdA1CommandAdminUpdateCredentials "A request to edit an admin's credentials."]
    [record IdA1CommandAdminUpdateCredentials
      [documentation adminId "The admin."]
      [field adminId cb:UUID]
      [documentation idName "The admin's new ID name."]
      [field idName [cb:Option cb:String]]
      [documentation realName "The admin's new real name."]
      [field realName [cb:Option cb:String]]
      [documentation password "The admin's new password"]
      [field password [cb:Option IdA1Password]]
    ]

    [documentation IdA1CommandAdminUpdatePasswordExpiration "A request to update the admin's password expiration."]
    [record IdA1CommandAdminUpdatePasswordExpiration
      [documentation userId "The admin."]
      [field userId cb:UUID]
      [documentation set "The set behaviour."]
      [field set IdA1PasswordExpirationSet]
    ]

    [documentation IdA1CommandAuditSearchBegin "Start searching/listing audit records."]
    [record IdA1CommandAuditSearchBegin
      [documentation parameters "The search parameters."]
      [field parameters IdA1AuditSearchParameters]
    ]

    [documentation IdA1CommandAuditSearchNext "Get the next page of audit search results."]
    [record IdA1CommandAuditSearchNext]

    [documentation IdA1CommandAuditSearchPrevious "Get the previous page of audit search results."]
    [record IdA1CommandAuditSearchPrevious]

    [documentation IdA1CommandMailTest "Send a test email to a given address."]
    [record IdA1CommandMailTest
      [documentation address "The target email address."]
      [field address cb:String]
      [documentation token "The email token."]
      [field token cb:String]
    ]

    [documentation IdA1CommandMaintenanceModeSet "Move the server to/from maintenance mode."]
    [record IdA1CommandMaintenanceModeSet
      [documentation message "The message (if maintenance mode is to be turned on)."]
      [field message [cb:Option cb:String]]
    ]

    [documentation IdA1CommandLogin "A request to log in."]
    [record IdA1CommandLogin
      [documentation userName "The username."]
      [field userName cb:String]
      [documentation password "The password."]
      [field password cb:String]
      [documentation metadata "The extra metadata"]
      [field metadata [cb:Map cb:String cb:String]]
    ]

    ;
    ; User commands.
    ;

    [documentation IdA1CommandUserBanCreate "Ban a user."]
    [record IdA1CommandUserBanCreate
      [documentation ban "The ban."]
      [field ban IdA1Ban]
    ]

    [documentation IdA1CommandUserBanDelete "Remove a ban on a user."]
    [record IdA1CommandUserBanDelete
      [documentation userId "The user."]
      [field userId cb:UUID]
    ]

    [documentation IdA1CommandUserBanGet "Get a ban on a user."]
    [record IdA1CommandUserBanGet
      [documentation userId "The user."]
      [field userId cb:UUID]
    ]

    [documentation IdA1CommandUserCreate "Create a user."]
    [record IdA1CommandUserCreate
      [documentation userId "The user."]
      [field userId [cb:Option cb:UUID]]
      [documentation idName "The user ID name."]
      [field idName cb:String]
      [documentation realName "The user real name."]
      [field realName cb:String]
      [documentation email "The user email."]
      [field email cb:String]
      [documentation password "The user password."]
      [field password IdA1Password]
    ]

    [documentation IdA1CommandUserDelete "Delete a user."]
    [record IdA1CommandUserDelete
      [documentation userId "The user."]
      [field userId cb:UUID]
    ]

    [documentation IdA1CommandUserEmailAdd "Add an email address to the given user."]
    [record IdA1CommandUserEmailAdd
      [documentation userId "The user."]
      [field userId cb:UUID]
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandUserEmailRemove "Remove an email address from the given user."]
    [record IdA1CommandUserEmailRemove
      [documentation userId "The user."]
      [field userId cb:UUID]
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandUserGet "Get the given user."]
    [record IdA1CommandUserGet
      [documentation userId "The user."]
      [field userId cb:UUID]
    ]

    [documentation IdA1CommandUserGetByEmail "Get the user with the given email address."]
    [record IdA1CommandUserGetByEmail
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdA1CommandUserLoginHistory "Get the given user's login history."]
    [record IdA1CommandUserLoginHistory
      [documentation userId "The user."]
      [field userId cb:UUID]
    ]

    [documentation IdA1CommandUserSearchBegin "Start searching for users."]
    [record IdA1CommandUserSearchBegin
      [documentation parameters "The search parameters."]
      [field parameters IdA1UserSearchParameters]
    ]

    [documentation IdA1CommandUserSearchByEmailBegin "Start searching for users (by email)."]
    [record IdA1CommandUserSearchByEmailBegin
      [documentation parameters "The search parameters."]
      [field parameters IdA1UserSearchByEmailParameters]
    ]

    [documentation IdA1CommandUserSearchByEmailNext "Get the next page of user search results."]
    [record IdA1CommandUserSearchByEmailNext]

    [documentation IdA1CommandUserSearchByEmailPrevious "Get the previous page of user search results."]
    [record IdA1CommandUserSearchByEmailPrevious]

    [documentation IdA1CommandUserSearchNext "Get the next page of user search results."]
    [record IdA1CommandUserSearchNext]

    [documentation IdA1CommandUserSearchPrevious "Get the previous page of user search results."]
    [record IdA1CommandUserSearchPrevious]

    [documentation IdA1CommandUserUpdateCredentials "A request to fetch the user's own profile."]
    [record IdA1CommandUserUpdateCredentials
      [documentation userId "The user."]
      [field userId cb:UUID]
      [documentation idName "The user's new ID name."]
      [field idName [cb:Option cb:String]]
      [documentation realName "The user's new real name."]
      [field realName [cb:Option cb:String]]
      [documentation password "The user's new password"]
      [field password [cb:Option IdA1Password]]
    ]

    [documentation IdA1CommandUserUpdatePasswordExpiration "A request to update the user's password expiration."]
    [record IdA1CommandUserUpdatePasswordExpiration
      [documentation userId "The user."]
      [field userId cb:UUID]
      [documentation set "The set behaviour."]
      [field set IdA1PasswordExpirationSet]
    ]

    ;
    ; Admin responses.
    ;

    [documentation IdA1ResponseBlame "A blame assignment."]
    [variant IdA1ResponseBlame
      [documentation BlameClient "The client sent a bad response."]
      [case BlameClient]
      [documentation BlameServer "Something went wrong on the server."]
      [case BlameServer]
    ]

    [documentation IdA1ResponseAdminBanCreate "A response to IdA1CommandAdminBanCreate."]
    [record IdA1ResponseAdminBanCreate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation ban "The ban."]
      [field ban IdA1Ban]
    ]

    [documentation IdA1ResponseAdminBanDelete "A response to IdA1CommandAdminBanDelete."]
    [record IdA1ResponseAdminBanDelete
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
    ]

    [documentation IdA1ResponseAdminBanGet "A response to IdA1CommandAdminBanGet."]
    [record IdA1ResponseAdminBanGet
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation ban "The ban."]
      [field ban [cb:Option IdA1Ban]]
    ]

    [documentation IdA1ResponseAdminCreate "A response to IdA1CommandAdminCreate."]
    [record IdA1ResponseAdminCreate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation admin "The admin."]
      [field admin IdA1Admin]
    ]

    [documentation IdA1ResponseAdminDelete "A response to IdA1CommandAdminDelete."]
    [record IdA1ResponseAdminDelete
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
    ]

    [documentation IdA1ResponseAdminGet "A response to IdA1CommandAdminGet."]
    [record IdA1ResponseAdminGet
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation admin "The admin."]
      [field admin [cb:Option IdA1Admin]]
    ]

    [documentation IdA1ResponseAdminSearchBegin "A response to IdA1CommandAdminSearchBegin."]
    [record IdA1ResponseAdminSearchBegin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The first page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSearchNext "A response to IdA1CommandAdminSearchNext."]
    [record IdA1ResponseAdminSearchNext
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The next page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSearchPrevious "A response to IdA1CommandAdminSearchPrevious."]
    [record IdA1ResponseAdminSearchPrevious
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The previous page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSearchByEmailBegin "A response to IdA1CommandAdminSearchByEmailBegin."]
    [record IdA1ResponseAdminSearchByEmailBegin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The first page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSearchByEmailNext "A response to IdA1CommandAdminSearchByEmailNext."]
    [record IdA1ResponseAdminSearchByEmailNext
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The next page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSearchByEmailPrevious "A response to IdA1CommandAdminSearchByEmailPrevious."]
    [record IdA1ResponseAdminSearchByEmailPrevious
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The previous page of results."]
      [field page [IdA1Page IdA1AdminSummary]]
    ]

    [documentation IdA1ResponseAdminSelf "A response to IdA1CommandAdminSelf."]
    [record IdA1ResponseAdminSelf
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation admin "The admin."]
      [field admin IdA1Admin]
    ]

    [documentation IdA1ResponseAdminUpdate "A response to IdA1CommandAdminUpdateCredentials."]
    [record IdA1ResponseAdminUpdate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation admin "The admin."]
      [field admin IdA1Admin]
    ]

    [documentation IdA1ResponseAuditSearchBegin "A response to IdA1CommandAuditSearchBegin."]
    [record IdA1ResponseAuditSearchBegin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The first page of results."]
      [field page [IdA1Page IdA1AuditEvent]]
    ]

    [documentation IdA1ResponseAuditSearchNext "A response to IdA1CommandAuditSearchNext."]
    [record IdA1ResponseAuditSearchNext
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The next page of results."]
      [field page [IdA1Page IdA1AuditEvent]]
    ]

    [documentation IdA1ResponseAuditSearchPrevious "A response to IdA1CommandAuditSearchPrevious."]
    [record IdA1ResponseAuditSearchPrevious
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The previous page of results."]
      [field page [IdA1Page IdA1AuditEvent]]
    ]

    [documentation IdA1ResponseMaintenanceModeSet "A response to IdA1CommandMaintenanceModeSet."]
    [record IdA1ResponseMaintenanceModeSet
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation message "The response message."]
      [field message cb:String]
    ]

    [documentation IdA1ResponseMailTest "A response to IdA1CommandMailTest."]
    [record IdA1ResponseMailTest
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation token "The unique token that was placed into the test email."]
      [field token cb:String]
    ]

    ;
    ; User responses.
    ;

    [documentation IdA1ResponseUserBanCreate "A response to IdA1CommandUserBanCreate."]
    [record IdA1ResponseUserBanCreate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation ban "The ban."]
      [field ban IdA1Ban]
    ]

    [documentation IdA1ResponseUserBanDelete "A response to IdA1CommandUserBanDelete."]
    [record IdA1ResponseUserBanDelete
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
    ]

    [documentation IdA1ResponseUserBanGet "A response to IdA1CommandUserBanGet."]
    [record IdA1ResponseUserBanGet
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation ban "The ban."]
      [field ban [cb:Option IdA1Ban]]
    ]

    [documentation IdA1ResponseUserCreate "A response to IdA1CommandUserCreate."]
    [record IdA1ResponseUserCreate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user IdA1User]
    ]

    [documentation IdA1ResponseUserDelete "A response to IdA1CommandUserDelete."]
    [record IdA1ResponseUserDelete
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
    ]

    [documentation IdA1ResponseUserGet "A response to IdA1CommandUserGet."]
    [record IdA1ResponseUserGet
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user [cb:Option IdA1User]]
    ]

    [documentation IdA1ResponseUserSearchBegin "A response to IdA1CommandUserSearchBegin."]
    [record IdA1ResponseUserSearchBegin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The first page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserSearchNext "A response to IdA1CommandUserSearchNext."]
    [record IdA1ResponseUserSearchNext
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The next page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserSearchPrevious "A response to IdA1CommandUserSearchPrevious."]
    [record IdA1ResponseUserSearchPrevious
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The previous page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserSearchByEmailBegin "A response to IdA1CommandUserSearchByEmailBegin."]
    [record IdA1ResponseUserSearchByEmailBegin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The first page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserSearchByEmailNext "A response to IdA1CommandUserSearchByEmailNext."]
    [record IdA1ResponseUserSearchByEmailNext
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The next page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserSearchByEmailPrevious "A response to IdA1CommandUserSearchByEmailPrevious."]
    [record IdA1ResponseUserSearchByEmailPrevious
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation page "The previous page of results."]
      [field page [IdA1Page IdA1UserSummary]]
    ]

    [documentation IdA1ResponseUserUpdate "A response to IdA1CommandUserUpdateCredentials."]
    [record IdA1ResponseUserUpdate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user IdA1User]
    ]

    [documentation IdA1ResponseUserLoginHistory "A response to IdA1CommandUserLoginHistory."]
    [record IdA1ResponseUserLoginHistory
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation requestId "The user's login history."]
      [field history [cb:List IdA1Login]]
    ]

    ;
    ; General responses.
    ;

    [documentation IdA1ResponseError "An error response."]
    [record IdA1ResponseError
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation errorCode "The error code."]
      [field errorCode cb:String]
      [documentation message "The error message."]
      [field message cb:String]
      [documentation attributes "The error attributes."]
      [field attributes [cb:Map cb:String cb:String]]
      [documentation remediatingAction "The remediating action, if any."]
      [field remediatingAction [cb:Option cb:String]]
      [documentation blame "The blame assignment."]
      [field blame IdA1ResponseBlame]
    ]

    [documentation IdA1ResponseLogin "A response to IdA1CommandLogin."]
    [record IdA1ResponseLogin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation admin "The admin."]
      [field admin IdA1Admin]
    ]

    [documentation IdA "The Admin protocol."]
    [protocol IdA
      [version 1
        [types-added
          IdA1CommandAdminBanCreate
          IdA1CommandAdminBanDelete
          IdA1CommandAdminBanGet
          IdA1CommandAdminCreate
          IdA1CommandAdminDelete
          IdA1CommandAdminEmailAdd
          IdA1CommandAdminEmailRemove
          IdA1CommandAdminGet
          IdA1CommandAdminGetByEmail
          IdA1CommandAdminPermissionGrant
          IdA1CommandAdminPermissionRevoke
          IdA1CommandAdminSearchBegin
          IdA1CommandAdminSearchByEmailBegin
          IdA1CommandAdminSearchByEmailNext
          IdA1CommandAdminSearchByEmailPrevious
          IdA1CommandAdminSearchNext
          IdA1CommandAdminSearchPrevious
          IdA1CommandAdminSelf
          IdA1CommandAdminUpdateCredentials
          IdA1CommandAdminUpdatePasswordExpiration
          IdA1CommandAuditSearchBegin
          IdA1CommandAuditSearchNext
          IdA1CommandAuditSearchPrevious
          IdA1CommandLogin
          IdA1CommandMailTest
          IdA1CommandMaintenanceModeSet
          IdA1CommandUserBanCreate
          IdA1CommandUserBanDelete
          IdA1CommandUserBanGet
          IdA1CommandUserCreate
          IdA1CommandUserDelete
          IdA1CommandUserEmailAdd
          IdA1CommandUserEmailRemove
          IdA1CommandUserGet
          IdA1CommandUserGetByEmail
          IdA1CommandUserLoginHistory
          IdA1CommandUserSearchBegin
          IdA1CommandUserSearchByEmailBegin
          IdA1CommandUserSearchByEmailNext
          IdA1CommandUserSearchByEmailPrevious
          IdA1CommandUserSearchNext
          IdA1CommandUserSearchPrevious
          IdA1CommandUserUpdateCredentials
          IdA1CommandUserUpdatePasswordExpiration
          IdA1ResponseAdminBanCreate
          IdA1ResponseAdminBanDelete
          IdA1ResponseAdminBanGet
          IdA1ResponseAdminCreate
          IdA1ResponseAdminDelete
          IdA1ResponseAdminGet
          IdA1ResponseAdminSearchBegin
          IdA1ResponseAdminSearchByEmailBegin
          IdA1ResponseAdminSearchByEmailNext
          IdA1ResponseAdminSearchByEmailPrevious
          IdA1ResponseAdminSearchNext
          IdA1ResponseAdminSearchPrevious
          IdA1ResponseAdminSelf
          IdA1ResponseAdminUpdate
          IdA1ResponseAuditSearchBegin
          IdA1ResponseAuditSearchNext
          IdA1ResponseAuditSearchPrevious
          IdA1ResponseError
          IdA1ResponseLogin
          IdA1ResponseMailTest
          IdA1ResponseMaintenanceModeSet
          IdA1ResponseUserBanCreate
          IdA1ResponseUserBanDelete
          IdA1ResponseUserBanGet
          IdA1ResponseUserCreate
          IdA1ResponseUserDelete
          IdA1ResponseUserGet
          IdA1ResponseUserLoginHistory
          IdA1ResponseUserSearchBegin
          IdA1ResponseUserSearchByEmailBegin
          IdA1ResponseUserSearchByEmailNext
          IdA1ResponseUserSearchByEmailPrevious
          IdA1ResponseUserSearchNext
          IdA1ResponseUserSearchPrevious
          IdA1ResponseUserUpdate
        ]
      ]
    ]

8. API Access
Previous
8. API Access
Up
8.2. User Protocol
Next
io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-rc0003