# 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>

    # 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>

    REG_ID=`echo '{"header": {"method": "sms","action": "init"},
         "payload":{"phone_number": "004367761753112",
                    "email": "[e-mail]"}}' | \
    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>

    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:

    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>

    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>

    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>

    # 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>

    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>

    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>

    # 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>

    REG_ID=`echo '{"header": {"method": "sms","action": "init"},
         "payload":{"phone_number": "004367761753112",
                    "email": "[e-mail]",
                    "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>

    # 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>

    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>

    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:

    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>

    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>

    # 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>

    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>

    # 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>

    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>

    # 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

{
  "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:

{
  "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"`):

{
  "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)

{
  "@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"
}