io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-rc0001
8.1. Admin Protocol
Previous
8. API Access
Up
8.3. JavaDoc
Next

# 8.2. User Protocol

- 8.2.1. Versioning
- 8.2.2. Health
- 8.2.3. Version 1.0
  - 8.2.3.1. Encoding
  - 8.2.3.2. Login
  - 8.2.3.3. Commands
  - 8.2.3.4. Generated Documentation
- 8.2.4. Schemas

## 8.2.1. Versioning

1
The User API service exposes one or more versions of the User protocol. The service uses the verdant protocol to advertise which versions of the User protocol are available. Executing a GET request to the root endpoint will yield a verdant message showing which versions of the User protocol are available. The User protocol is assigned the protocol identifier ed628c5a-0182-36ab-bee3-5fe6f6a21894.
2
As an example, the following shows that the User protocol version 1 is available at /user/1/0/:

### 8.2.1.3. Verdant Example

    $ curl https://idstore.example.com:50000/ | hexdump
    0000:0000 | 00 00 00 01  00 00 00 01  ED 62 8C 5A  01 82 36 AB | ........íb.Z..6«
    0000:0010 | BE E3 5F E6  F6 A2 18 94  00 00 00 01  00 00 00 00 | ¾ã_æö¢..........
    0000:0020 | 00 00 00 0A  2F 75 73 65  72 2F 31 2F  30 2F       | ..../user/1/0/

## 8.2.2. Health

1
The User 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.2.3. Version 1.0

## 8.2.3.1. Encoding

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

## 8.2.3.2. Login

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

## 8.2.3.3. Commands

1
After logging in successfully, send commands of type IdU1Command* to /user/1/0/command. Failed commands will yield a value of type IdU1ResponseError, whilst successful results will yield values of type IdU1Response*.

## 8.2.3.4. Generated Documentation

1
Generated documentation for the Cedarbridge schemas is available:

### 8.2.3.4.2. Schema Documentation

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

## 8.2.4. Schemas

### 8.2.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.user.cb]

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

    [documentation IdU1Password "Information for a hashed password."]
    [record IdU1Password
      [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 IdU1TimestampUTC "A UTC timestamp value."]
    [record IdU1TimestampUTC
      [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 IdU1User "A user."]
    [record IdU1User
      [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 account was created."]
      [field timeCreated IdU1TimestampUTC]
      [documentation timeUpdated "The time the account was updated."]
      [field timeUpdated IdU1TimestampUTC]
      [documentation password "The user password."]
      [field password IdU1Password]
    ]

    ;
    ; Commands.
    ;

    [documentation IdU1CommandLogin "A request to log in."]
    [record IdU1CommandLogin
      [documentation userName "The username."]
      [field userName cb:String]
      [documentation password "The password."]
      [field password cb:String]
      [documentation metadata "Extra metadata included with the login request."]
      [field metadata [cb:Map cb:String cb:String]]
    ]

    [documentation IdU1CommandUserSelf "A request to fetch the user's own profile."]
    [record IdU1CommandUserSelf]

    [documentation IdU1CommandEmailAddBegin "A request to add an email address."]
    [record IdU1CommandEmailAddBegin
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdU1CommandEmailRemoveBegin "A request to remove an email address."]
    [record IdU1CommandEmailRemoveBegin
      [documentation email "The email address."]
      [field email cb:String]
    ]

    [documentation IdU1CommandEmailAddPermit "A request to complete an email address challenge."]
    [record IdU1CommandEmailAddPermit
      [documentation token "The challenge token."]
      [field token cb:String]
    ]

    [documentation IdU1CommandEmailRemovePermit "A request to complete an email address challenge."]
    [record IdU1CommandEmailRemovePermit
      [documentation token "The challenge token."]
      [field token cb:String]
    ]

    [documentation IdU1CommandEmailAddDeny "A request to complete an email address challenge."]
    [record IdU1CommandEmailAddDeny
      [documentation token "The challenge token."]
      [field token cb:String]
    ]

    [documentation IdU1CommandEmailRemoveDeny "A request to complete an email address challenge."]
    [record IdU1CommandEmailRemoveDeny
      [documentation token "The challenge token."]
      [field token cb:String]
    ]

    [documentation IdU1CommandRealnameUpdate "A request to update the user's real name."]
    [record IdU1CommandRealnameUpdate
      [documentation name "The new name."]
      [field name cb:String]
    ]

    [documentation IdU1CommandPasswordUpdate "A request to update the user's password."]
    [record IdU1CommandPasswordUpdate
      [documentation password "The new password."]
      [field password cb:String]
      [documentation passwordConfirm "The password confirmation."]
      [field passwordConfirm cb:String]
    ]

    ;
    ; Responses.
    ;

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

    [documentation IdU1ResponseError "An error response."]
    [record IdU1ResponseError
      [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 IdU1ResponseBlame]
    ]

    [documentation IdU1ResponseLogin "A response to IdU1CommandLogin."]
    [record IdU1ResponseLogin
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user IdU1User]
    ]

    [documentation IdU1ResponseUserSelf "A response to IdU1CommandUserSelf."]
    [record IdU1ResponseUserSelf
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user IdU1User]
    ]

    [documentation IdU1ResponseUserUpdate "A response to various update commands."]
    [record IdU1ResponseUserUpdate
      [documentation requestId "The ID of the request that yielded this response."]
      [field requestId cb:UUID]
      [documentation user "The user."]
      [field user IdU1User]
    ]

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

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

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

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

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

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

    ;
    ; Protocol.
    ;

    [documentation IdU "The User protocol."]
    [protocol IdU
      [version 1
        [types-added
          IdU1CommandEmailAddBegin
          IdU1CommandEmailAddDeny
          IdU1CommandEmailAddPermit
          IdU1CommandEmailRemoveBegin
          IdU1CommandEmailRemoveDeny
          IdU1CommandEmailRemovePermit
          IdU1CommandLogin
          IdU1CommandPasswordUpdate
          IdU1CommandRealnameUpdate
          IdU1CommandUserSelf
          IdU1ResponseEmailAddBegin
          IdU1ResponseEmailAddDeny
          IdU1ResponseEmailAddPermit
          IdU1ResponseEmailRemoveBegin
          IdU1ResponseEmailRemoveDeny
          IdU1ResponseEmailRemovePermit
          IdU1ResponseError
          IdU1ResponseLogin
          IdU1ResponseUserSelf
          IdU1ResponseUserUpdate
        ]
      ]
    ]

8.1. Admin Protocol
Previous
8. API Access
Up
8.3. JavaDoc
Next
io7m | single-page | multi-page | epub | Idstore User Manual 1.0.0-rc0001