---
# System prepended metadata

title: RegAPIv3 Sequence
tags: [im4dec]

---

# RegAPI v3 Sequences

#### Content
* [SMS Sequence](#SMS-Sequence)
  * [Re-Send SMS Code](#Re-send-SMS-Code)
  * [Update Phone Number](#Update-Phone-Number)
  * [Request Plain Text Credentials](#Request-Plain-Text-Credentials)
* [ID Austria Sequence](#ID-Austria-Sequence)
* [Delete RegID Sequence](#Delete-RegID-Sequence)
* [Delete User Sequence](#Delete-User-Sequence)
* [Retrieve Configuration (root/user-config)](#Get-root--user-config)
* [List of Statuses](#List-of-Statuses)
* [Data Structures](#Structures)

Links:
* [Old RegAPI HackMD](https://hackmd.io/QXGZljmsSyGDzXHd_7Fo1g) (DEPRECATED)
* Swagger from RegAPI v1&v2: https://app.test.dec112.eu/api/
* [D1 RegAPI Sequence](https://docs.google.com/document/d/1PYZq8NVXlprOqfM3DefIPuxDl5Qjilrh9eMaM8wffCg/edit#heading=h.21ddyutzr0a)
* [D1 RegAPI Components](https://docs.google.com/document/d/1PYZq8NVXlprOqfM3DefIPuxDl5Qjilrh9eMaM8wffCg/edit#heading=h.4zo0wpqblqsu)

## SMS Sequence

1) DEC App retrieves location of RegAPI from root config and
    creates DID + stores private key
    
    <details><summary>DEC112 App</summary>
    
    * retrieve root config: `GET /api/v3/root/config`
        * store regApiUrl returned from GET request
    * create DID: via **oydid npm** `create()`
        * store DID and associated privated key returned by `create()`

    </details>
2) DEC App authenticates with own DID towards RegAPI

    <details><summary>DEC112 App</summary>
    
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`
  
    </details>
    
    <details><summary>Description of API for DID Auth</summary>
    
      a) `POST /oydid/init`
          Body: `{"session_id": string, "did": string}`
          Response: `{"challenge": string}`
      b) `POST /oydid/token`
          Body: `{"session_id": string, "signed_challenge": string}`
          Comment: challenge must be signed with private key from first public key published in DID
          Response: `{"access_token": string}`
    
    </details>
        
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    REGAPI="https://regapi.test-feb24.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>
    
3) DEC App requests creating new user
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN` -> at the same time identity through DID
    Body:
    
       {
         "header": {
           "method": "sms",
           "action": "init"
         },
         "payload":{
           "phone_number": string,
           "model?": string,
           "lang?": "de",
           "purpose?": "chat",
           "applicaiton?": string
         }
       }

    <details><summary>DEC112 App</summary>
    
    to request creating a new user through SMS verification, the DEC112 App has to submit a POST or PUT request to the RegAPI
    * use the OAuth2 Bearer Token to authenticate against the API
    * store `reg_id` returned by the PUT request as session token for subsequent requests
  
    </details>

    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    REG_ID=`echo '{"header": {"method": "sms","action": "init"},
         "payload":{"phone_number": "004367761753112",
                    "email": "christoph.fabianek@gmail.com"}}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- -s \
         -X PUT $REGAPI/api/v3/register | \
    jq -r '.reg_id'`
    ```
  
    </details>

4) RegAPI puts information on Redis
    * create hashmap with reg_id as reference
    * publish reg_id to 'sms' channel
    * set status in hashmap to "SMS plugin triggered"
    * return reg_id as response to `PUT /api/v3/register`

5) SMS Plugin is subscribed to 'sms' channel
    * generates 6 digit code
    * sends SMS to provided phone number (during tests: email)
    * set status to "SMS sent"

6) DEC App sends code received via SMS to RegAPI
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN`
    Body:
    
       {
         "header": {
           "reg_id": string
           "method": "sms",
           "action": "SmsVerificationCode"
         },
         "payload":{
           "sms_code": string
         }
       }

    <details><summary>DEC112 App</summary>
    
    to submit the Code that the user received via SMS, the DEC112 App  has to submit a PUT request to the RegAPI
  
    </details>

    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    CODE=12345678
    echo '{"header": {"method": "sms","action": "SmsVerificationCode"},
           "payload":{}}' | \
    jq --arg reg_id "$REG_ID" '.header += {"reg_id": $reg_id}' | \
    jq --arg code "$CODE" '.payload += {"sms_code": $code}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- \
         -X PUT $REGAPI/api/v3/register
    ```
    </details>

7) RegAPI puts information on Redis
    * add JSON encoded payload to SmsVerificationCode key
    * trigger 'sms' channel
    * set status for reg_id to "SmsVerificationCode received, SMS plugin triggered"
    * return reg_id as response to `PUT /api/v3/register`

8) SMS Plugin is subscribed to 'sms' channel
    * compares received code in payload with sms_code
    * if correct
        * set status: "SMS verification passed"
        * create Verifiable Credential as [described here](https://hackmd.io/UQB2mHk9RTCVJRc1xirVjw?view#SMS-Plugin)
        * encrypt VC, and 
        * store on Redis in field `identity_encrypted`
    * if not correct
        * set status: "SMS verification failed"
    
9) RegAPI publishes reg_id to 'sip' channel
    * starting condition: DEC App triggers via `GET /api/v3/register/:reg_id`
    * publish reg_id to 'sip' channel when status includes "verification passed"
        * set status to "SIP plugin triggered"

    <details><summary>DEC112 App</summary>
    
    the DEC112 App needs to poll the RegAPI to retrieve the current status; this polling can also trigger subsequent steps in the RegAPI, here: pushing the request after successful identification of the user to the "SIP Plugin"
    * perform GET Request for reg_id of the user onboarding process
  
    </details>

    <details><summary>Commands to test on command line</summary>
    
    check status:
    ```bash=
    curl -H "Authorization: Bearer $TOKEN" \
         "$REGAPI/api/v3/register?reg_id=$REG_ID"
    ```
    </details>

10) SIP Plugin is subscribed to 'sip' channel
    * create SIP credentials in Kamailio database
    * encrypt SIP credentials with public key
    * set status to "SIP credentials created"

11) DEC App requests and processes SIP credentials
    * `GET /api/v3/register/:reg_id`
    * decrypt SIP credentials
    * store locally

    <details><summary>DEC112 App</summary>
    
    after the RegAPI has performed the complete workflow (status is `SIP credentials created`) the following information is returned back upon querying the RegAPI (`GET /api/v3/register/:reg_id`):
    * SIP Credentials (key: `sip_credentials`)
    * secret token for deleting the account (key: `delete_token`)
    * Verifiable Credential as attestation for identiy (key: `identity`)
  
    &nbsp;
    all information is encrypted with the public key from the initial DID and need to be decrypted before the data is stored by the DEC112 App
    * via **oydid npm** `decrypt(encrypted_data, privateKey)`
    * since the `decrypt` function requires a MultiFormat base58btc encoded key and the inital method provides only a hex encoded key, it is necessary to convert the key via **oydid npm** `hexToMulti(privateKeyHex)`
    </details>
    
    <details><summary>Commands to test on command line</summary>

    ```bash=
    curl -s -H "Authorization: Bearer $TOKEN" \
         "$REGAPI/api/v3/register?reg_id=$REG_ID" |\
    jq -c '.sip.sip_credentials' | \
    oydid decrypt --doc-enc `cat "${DID:8:10}_private_key.enc"`
    ```
    </details>

### Re-send SMS Code

Request to re-send the SMS Code for a user can be performed during the SMS Sequence and requires an existing `:reg_id`; an SMS re-send can only be performed 3 times

* DEC App requests re-sending the SMS Code
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN`
    Body:
    
       {
         "header": {
           "reg_id": string
           "method": "sms",
           "action": "resend"
         }
       }
    <details><summary>DEC112 App</summary>
    
    to request resending the SMS Code, the DEC112 App has to submit a PUT request to the RegAPI
    * use an OAuth2 Bearer Token to authenticate against the API
    * use the `:reg_id` from the original request in the header section
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    echo '{"header": {"method": "sms","action": "resend"}}' | \
    jq --arg reg_id "$REG_ID" '.header += {"reg_id": $reg_id}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- \
         -X PUT $REGAPI/api/v3/register
    ```
    </details>

### Update Phone Number

Requirements:
* perform SMS Code Verification
* receive Verifiable Credential for phone number
* don't trigger creating SIP Credentials
  * keep same SIP credentials (phone number and SIP credentials are actually not linked!)

Sequence:

1) DEC App authenticates with own DID towards RegAPI

    <details><summary>DEC112 App</summary>
    
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`
  
    </details>
    
    <details><summary>Description of API for DID Auth</summary>
    
      a) `POST /oydid/init`
          Body: `{"session_id": string, "did": string}`
          Response: `{"challenge": string}`
      b) `POST /oydid/token`
          Body: `{"session_id": string, "signed_challenge": string}`
          Comment: challenge must be signed with private key from first public key published in DID
          Response: `{"access_token": string}`
    
    </details>
        
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>

2) DEC App requests re-sending the SMS Code
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN`
    Body:
    
       {
         "header": {
           "method": "sms",
           "action": "new_number"
         },
         "payload":{
           "phone_number": string
           "lang?": "de"
         }
       }
    <details><summary>DEC112 App</summary>
    
    to request updating the phone number, the DEC112 App has to submit a POST or PUT request to the RegAPI
    * use an OAuth2 Bearer Token to authenticate against the API
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    REG_ID=`echo '{"header": {"method": "sms","action": "new_number"},
         "payload":{"phone_number": "004366460850"}}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- -s \
         -X PUT $REGAPI/api/v3/register | \
    jq -r '.reg_id'`
    ```
    </details>

3) RegAPI puts information on Redis
    * create hashmap with reg_id as reference
    * publish reg_id to 'sms' channel
    * set status in hashmap to "SMS plugin triggered"
    * return reg_id as response to `PUT /api/v3/register`

4) SMS Plugin is subscribed to 'sms' channel
    * generates 6 digit code
    * sends SMS to provided phone number
    * set status to "SMS sent"

5) DEC App sends code received via SMS to RegAPI
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN`
    Body:
    
       {
         "header": {
           "reg_id": string
           "method": "sms",
           "action": "SmsVerificationCode"
         },
         "payload":{
           "sms_code": string
         }
       }

    <details><summary>DEC112 App</summary>
    
    to submit the Code that the user received via SMS, the DEC112 App  has to submit a PUT request to the RegAPI
  
    </details>

    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    CODE=123456
    echo '{"header": {"method": "sms","action": "SmsVerificationCode"},
           "payload":{}}' | \
    jq --arg reg_id "$REG_ID" '.header += {"reg_id": $reg_id}' | \
    jq --arg code "$CODE" '.payload += {"sms_code": $code}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- \
         -X PUT $REGAPI/api/v3/register
    ```
    </details>

6) RegAPI puts information on Redis
    * add JSON encoded payload to SmsVerificationCode key
    * trigger 'sms' channel
    * set status for reg_id to "SmsVerificationCode received, SMS plugin triggered"
    * return reg_id as response to `PUT /api/v3/register`

7) SMS Plugin is subscribed to 'sms' channel
    * compares received code in payload with sms_code
    * if correct
        * set status: "SMS verification for number update passed"
        * create Verifiable Credential as [described here](https://hackmd.io/UQB2mHk9RTCVJRc1xirVjw?view#SMS-Plugin)
        * encrypt VC, and 
        * store on Redis in field `identity_encrypted`
    * if not correct
        * set status: "SMS verification failed"
    
8) Client receives new VC for update number


### Request Plain Text Credentials

0) DEC App retrieves location of RegAPI from root config and
    creates DID + stores private key; afterwards DEC App authenticates with own DID towards RegAPI
    
    <details><summary>DEC112 App</summary>
    
    * retrieve root config: `GET /api/v3/root/config`
        * store regApiUrl returned from GET request
    * create DID: via **oydid npm** `create()`
        * store DID and associated privated key returned by `create()`
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`
    </details>
    
    <details><summary>Description of API for DID Auth</summary>
    
      a) `POST /oydid/init`
          Body: `{"session_id": string, "did": string}`
          Response: `{"challenge": string}`
      b) `POST /oydid/token`
          Body: `{"session_id": string, "signed_challenge": string}`
          Comment: challenge must be signed with private key from first public key published in DID
          Response: `{"access_token": string}`
    
    </details>

    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>
    
3) DEC App requests creating new user
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN` -> at the same time identity through DID
    Body:
    
       {
         "header": {
           "method": "sms",
           "action": "init"
         },
         "payload":{
           "phone_number": string,
           "model?": string,
           "lang?": "de",
           "purpose?": "chat",
           "application?": string
           "options":{
             "encrypt": "false"
           }
         }
       }

    <details><summary>DEC112 App</summary>
    
    to request creating a new user through SMS verification, the DEC112 App has to submit a POST or PUT request to the RegAPI
    * use the OAuth2 Bearer Token to authenticate against the API
    * store `reg_id` returned by the PUT request as session token for subsequent requests
  
    </details>

    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    REG_ID=`echo '{"header": {"method": "sms","action": "init"},
         "payload":{"phone_number": "004367761753112",
                    "email": "christoph.fabianek@gmail.com",
                    "options":{"encrypt":"false"}}}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- -s \
         -X PUT $REGAPI/api/v3/register | \
    jq -r '.reg_id'`
    ```
  
    </details>

remaining steps as in the other sequencs (without decryption at the end)

## ID Austria Sequence

1) DEC App creates DID + stores private key
    <details><summary>DEC112 App</summary>
    
    * retrieve root config: `GET /api/v3/root/config`
        * store regApiUrl returned from GET request
    * create DID: via **oydid npm** `create()`
        * store DID and associated privated key returned by `create()`

    </details>

2) DEC App authenticates with own DID towards RegAPI
    <details><summary>DEC112 App</summary>
    
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>
3) DEC App requests creating new user
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN` -> at the same time identity through DID
    Body:
    
       {
         "header": {
           "method": "id_austria",
           "action": "init"
         },
         "payload":{
           "phone_number?": string,
           "model?": string,
           "lang?": "de",
           "purpose?": "chat",
           "applicaiton?": string
         }
       }
    <details><summary>DEC112 App</summary>
    
    to request creating a new user through ID Austria verification, the DEC112 App has to submit a PUT request to the RegAPI
    * use the OAuth2 Bearer Token to authenticate against the API
    * store `reg_id` returned by the PUT request as session token for subsequent requests
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    REG_ID=`echo '{"header": {"method": "id_austria","action": "init"},
         "payload":{}}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- -s \
         -X PUT $REGAPI/api/v3/register | \
    jq -r '.reg_id'`
    ```
    </details>

4) RegAPI puts information on Redis
    * create hashmap with reg_id as reference
    * publish reg_id to 'id_austria' channel
    * set status in hashmap to "ID_AUSTRIA plugin triggered"
    * return reg_id as response to `PUT /api/v3/register`

5) ID Austria Plugin is subscribed to 'id_austria' channel
    * generate URL to be opened on client (using `reg_id`)
    * write ida_url to Redis
    * set status to "ID Austria URL generated"

6) DEC App queries status for `reg_id` and retrieves URL for ID Austria Verification
    * `GET /api/v3/register/:reg_id`
    * retrieve "url" and open in browser

    <details><summary>DEC112 App</summary>
    
    the response from the GET request includes an URL that needs to be opend in a browser window
    in this browser window the user performs the steps to identify herself/himself and service sends government issued ID
  
    </details>
    <details><summary>Commands to test on command line</summary>

    ```bash=
    curl -s -H "Authorization: Bearer $TOKEN" \
         "$REGAPI/api/v3/register?reg_id=$REG_ID" | \
    jq -r '.id_austria.ida_url'
    ```
    </details>
    
    :::info
    use the following test identity when using the A-Trust Q-System:
    * user: SP-9645542424
    * password: nQEy7aCeKC9lgL
    
    more identities: _[ID Austria Testidentitäten](https://eid.egiz.gv.at/anbindung/testidentitaeten/vordefinierte-testidentitaeten/)_
    :::
    
7) User logs in to ID Austria with credentials and signs Authentication Request

9) A-Trust returns citizen information and signed ID Austria identity to ID Austria Plugin

10) ID Austria Plugin sets status for `reg_id` to "ID_AUSTRIA verification passed"
      * create Verifiable Credential as [described here](https://hackmd.io/UQB2mHk9RTCVJRc1xirVjw?view#ID-Austria-Plugin)
      * encrypt VC, and 
      * store on Redis in field `identity_encrypted`


11) RegAPI publishes reg_id to 'sip' channel
    * starting condition: DEC App triggers via `GET /api/v3/register/:reg_id`
    * publish reg_id to 'sip' channel when status includes "verification passed"
        * set status to "SIP plugin triggered"
    <details><summary>DEC112 App</summary>
    
    the DEC112 App needs to poll the RegAPI to retrieve the current status; this polling can also trigger subsequent steps in the RegAPI, here: pushing the request after successful identification of the user to the "SIP Plugin"
    * perform GET Request for reg_id of the user onboarding process
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    check status:
    ```bash=
    curl -H "Authorization: Bearer $TOKEN" \
         "$REGAPI/api/v3/register?reg_id=$REG_ID"
    ```
    </details>

10) SIP Plugin is subscribed to 'sip' channel
    * create SIP credentials in Kamailio database
    * encrypt SIP credentials with public key
    * set status to "SIP credentials created"

11) DEC App requests and processes SIP credentials
    * `GET /api/v3/register/:reg_id`
    * decrypt SIP credentials
    * store locally
    <details><summary>DEC112 App</summary>
    
    after the RegAPI has performed the complete workflow (status is `SIP credentials created`) the following information is returned back upon querying the RegAPI (`GET /api/v3/register/:reg_id`):
    * SIP Credentials (key: `sip_credentials`)
    * secret token for deleting the account (key: `delete_token`)
    * Verifiable Credential as attestation for identiy (key: `identity`)
  
    &nbsp;
    all information is encrypted with the public key from the initial DID and need to be decrypted before the data is stored by the DEC112 App
    * via **oydid npm** `decrypt(encrypted_data, privateKey)`
    * since the `decrypt` function requires a MultiFormat base58btc encoded key and the inital method provides only a hex encoded key, it is necessary to convert the key via **oydid npm** `hexToMulti(privateKeyHex)`
    </details>
    <details><summary>Commands to test on command line</summary>

    ```bash=
    curl -s -H "Authorization: Bearer $TOKEN" \
         "$REGAPI/api/v3/register?reg_id=$REG_ID" |\
    jq -c '.sip.sip_credentials' | \
    oydid decrypt --doc-enc `cat "${DID:8:10}_private_key.enc"`
    ```
    </details>

## Delete RegID Sequence
The DEC112 App does not need to implement this sequence - see notes below.

1) Client authenticates with own DID towards RegAPI 
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>

2) Delete / Reset `reg_id` Object
    `DELETE /api/v3/register/:reg_id`

    <details><summary>Commands to test on command line</summary>

    ```bash=
    curl -H "Authorization: Bearer $TOKEN" \
        -X DELETE "$REGAPI/api/v3/register?reg_id=$REG_ID"
    ```
    </details>

Notes: 
* every hour all RegIDs older than 24 hours will be deleted automatically
* deleting the RegID does (of course) not delete the associated user -> see next sequence

## Delete User Sequence
1) DEC App authenticates with own DID towards RegAPI 
    <details><summary>DEC112 App</summary>
    
    * retrieve root config: `GET /api/v3/root/config`
        * store regApiUrl returned from GET request
    * create DID: via **oydid npm** `create()`
        * store DID and associated privated key returned by `create()`
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`

    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
    
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`
    ```
    </details>

2) DEC App requests deleting existing user
    `PUT /api/v3/register`
    Header: `Authorization: Bearer $TOKEN` -> at the same time identity through DID
    Body:
    
       {
         "header": {
           "method": "sip",
           "action": "delete_user"
         },
         "payload":{
           "username": string
         }
       }
    <details><summary>DEC112 App</summary>
    
    to request deleting a user, the DEC112 App has to submit a PUT request to the RegAPI
    * use the OAuth2 Bearer Token to authenticate against the API
    * store `reg_id` returned by the PUT request as session token for subsequent requests
  
    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    REG_ID=`echo '{"header": {"method": "sip","action": "delete_user"},
         "payload":{"username": "abc"}}' | \
    curl -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d @- -s \
         -X PUT $REGAPI/api/v3/register | \
    jq -r '.reg_id'`
    ```
    </details>
    
## Get root / user config
1) DEC App authenticates with own DID towards RegAPI 
    <details><summary>DEC112 App</summary>
    
    * retrieve root config: `GET /api/v3/root/config`
        * store regApiUrl returned from GET request
    * create DID: via **oydid npm** `create()`
        * store DID and associated privated key returned by `create()`
    * retrieve OAuth2 Bearer Token: via **oydid npm** `didAuth(DID, privateKey, regApiUrl)`

    </details>
    <details><summary>Commands to test on command line</summary>
    
    ```bash=
    # prerequisite: oydid, curl, jq installed (eg. in oydeu/oydid-cli)
    docker run -it --rm oydeu/oydid-cli:latest
      
    # REGAPI="http://localhost:3600"
    REGAPI="https://regapi.staging.dec112.eu"
    DID=`echo '' | oydid create --json --add-x25519pubkey-keyAgreement | jq -r '.did'`
    TOKEN=`oydid auth $DID $REGAPI --json | jq -r '.access_token'`

    # retrieve root config
    curl $REGAPI/api/v3/config/root
  
    # retrieve user config (requires authentication)
    curl -H "Authorization: Bearer $TOKEN" $REGAPI/api/v3/config/user
    ```
    </details>

## List of Statuses

| Code | Text | Description |
| ---- | ---- | ----------- |
|<tr><td colspan="3">set by RegAPI (range: 1001-1099)</td></tr>|
| 1001 | `initial` | initial state with action `init` |
| 1002 | `{method} plugin triggered` | triggered plugin (usually specified in 'method') |
| 1003 | `{action} received, {method} plugin triggered` | triggered plugin specified in 'method' in 'action' |
| 1004 | `REG_ID removed` | after successful deletion of `:reg_id`in Redis |
|<tr><td colspan="3">set by SMS Plugin (range: 1100-1199)</td></tr>|
| 1100 | `SMS verification passed` | SMS verification successfully performed |
| 1101 | `SMS Plugin: SMS sent` | successfully sent SMS code |
| 1102 | `SMS Plugin: Email sent` | successfully sent code via Email (only in EMAIL_TEST_MODE) |
| 1103 | `SMS Plugin: cannot send SMS code` | error on sending SMS code |
| 1104 | `SMS Plugin: invalid input for 'SmsVerificationCode'` | payload provided by client cannot be parsed |
| 1105 | `SMS Plugin: invalid input in 'SmsVerificationCode'` | payload provided by client does not include 'sms_code' |
| 1106 | `SMS Plugin: invalid SMS code provided` | sms_code provided by client does not match code sent out |
| 1107 | `SMS Plugin: internal error in SMS code handling` | error on encrypting/decrypting SMS code |
| 1108 | `SMS Plugin: invalid phone number` | provided phone number does not match format provided in "PHONE_NUMBER_VERIFICATION" |
| 1109 | `SMS Plugin: SMS resend limit ({max}) reached` | too many requests for re-sending SMS |
| 1110 | `SMS Plugin: unknown action '{action}'` | given action cannot be processed |
|<tr><td colspan="3">set by ID-Austria Plugin (range: 1200-1299)</td></tr>|
| 1200 | `ID_AUSTRIA verification passed` | verification through ID Austria successfully performed |
| 1201 | `ID Austria URL generated` | URL for user to authenticate with ID Austria |
| 1202 | `ID Austria Plugin: invalid action` | unknown request |
| 1203 | `ID_AUSTRIA Plugin: invalid response` | error in processing the response A-Trust |
|<tr><td colspan="3">set by ID-Austria Plugin (range: 1000, 9001-9099)</td></tr>|
| 1000 | `SIP credentials created` | SIP plugin successfully created and onboarding completed |
| 9001 | `SIP Plugin: error on creating SIP credentials` | error in SIP Plugin |
| 9002 | `SIP Plugin: missing configuration 'SIP_SECRET'` | SIP_SECRET not configured (to be used with token for deleting users) |
| 9003 | `SIP Plugin: error on connecting to Kamailio DB` | connection information to Kamailio is not valid |
| 9004 | `SIP Plugin: error on writing subscriber table` | error in SQL INSERT command |

## Structures

### RegAPI Requests

```json=
{
  "header": {
    "method": "sms" | "id_austria" | "sip",
    "action": "init" | "SmsVerificationCode" | "resend" | "new_number" | "delete_user",
    "reg_id?": string | (empty for init action)
  },
  "payload":{
    "phone_number": string,
    "model?": string,
    "lang?": "de",
    "purpose?": "chat",
    "applicaiton?": string,
    "sms_code": string (only for action "SmsVerificationCode"),
    "username": string (only for action "sip")
    "options": {
      "redirect": "redirect_url after ID Austria is completed"
      "encrypt": "true" (default) | "false" | "jwe"
    }
  }
}
```

### RegAPI Response

for encrypted data:

```json=
{
  "reg_id": string,
  "status": integer,
  "status_text": string,
  "id_austria": {
    "ida_url": string,
    "vc": {
      "value": string,
      "nonce": string
    }
  },
  "sms": {
    "vc": {
      "value": string,
      "nonce": string
    }
  },
  "sip": {
    "sip_credentials": {
      "value": string,
      "nonce": string
    },
    "delete_token": string
  }
}
```
for unencrypted data (`options > encrypt: "false"`):

```json=
{
  "reg_id": string,
  "status": integer,
  "status_text": string,
  "id_austria": {
    "ida_url": string,
    "adresse": {
      "Tuer": string,
      "Stiege": string,
      "Strasse": string,
      "Ortschaft": string,
      "Hausnummer": string,
      "Postleitzahl": string,
      "Gemeindekennziffer": string,
      "Gemeindebezeichnung": string
    },
    "vorname": string,
    "nachname": string,
    "geburtsdatum": string,
    "eid-issuing-nation": string,
    "id-austria-completed": integer,
    "eid-signer-certificate": string
  },
  "sms": {
    "vc": {
      "value": string,
      "nonce": string
    }
  },
  "sip": {
    "sip_credentials": {
      "username": string,
      "password": string
    },
    "delete_token": string
  }
}
```

### DEC112Credential
(in Sphereon Wallet Onboarding)
```json=
{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": [
    "VerifiableCredential",
    "DEC112Credential"
  ],
  "issuer": "did:oyd:zQmX7WYhQCdHcdzfCLRj9tAUgRYar6pqAf2GXS7NQfoX6aE",
  "issuanceDate": string, // example: "2024-01-09T13:57:34Z"
  "credentialSubject": {
    "id": "did:oyd:zQmb1aZtsQa3YMy3giTubz2Te6QWioj1EgoUvpQcv2pgBTq",
    "id_austra": {
      "adresse": {
        "Tuer": string,
        "Stiege": string,
        "Strasse": string,
        "Ortschaft": string,
        "Hausnummer": string,
        "Postleitzahl": string,
        "Gemeindekennziffer": string,
        "Gemeindebezeichnung": string,
      },
      "vorname": string,
      "nachname": string,
      "geburtsdatum": string, // example: "1977-07-21",
      "eid-issuing-nation":  string, // example: "AT",
      "id-austria-completed": integer, // example: 1704808634,
      "eid-signer-certificate": string,
    },
    "sip": {
      "delete_token": string,
      "sip_credentials": {
        "password": string,
        "username": string,
      }
    }
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "verificationMethod": "did:oyd:zQmX7WYhQCdHcdzfCLRj9tAUgRYar6pqAf2GXS7NQfoX6aE",
    "proofPurpose": "assertionMethod",
    "proofValue": "z39...67g"
  },
  "identifier": "zQmZEEjr5aWofz9UTbTqPUt3VV3SLMWmebWmSoKYNeWrs1r",
  "expirationDate": "2024-04-09T13:57:34Z"
}
```