First access and password

First access and password recovery follow the same flow: the application starts the flow, the API returns a secure link (linkURL) and sends a PIN to the user by email or SMS. The application completes the flow by sending the PIN and the new password to that link, at /auth/change.

    sequenceDiagram
    participant C as Client
    participant A as Riversoft STCP DirectLink API
    participant U as User
    C->>A: GET /auth/firstaccess?u=<user> or /auth/forget?u=<user>
    A-->>C: 200 OK with linkURL (/auth/change?k=...)
    A-->>U: PIN by email or SMS
    U->>C: Enters the PIN and the new password
    C->>A: POST linkURL (k in the URL, p=PIN and z=new password in the body)
    A-->>C: 200 OK

Start the flow

For first access:

curl -i --get \
  --data-urlencode "u=$API_USER" \
  "$API_BASE/auth/firstaccess"

To recover the password:

curl -i --get \
  --data-urlencode "u=$API_USER" \
  "$API_BASE/auth/forget"

The response carries the secure link in linkURL, and the user receives the PIN by email or SMS. Keep the linkURL for the next step:

# use /auth/firstaccess for first access
export CHANGE_URL=$(curl -s --get --data-urlencode "u=$API_USER" "$API_BASE/auth/forget" | jq -r .linkURL)

Note

If Cloudflare Turnstile validation is enabled in the environment, also send the CF-Turnstile-Response header. See Cloudflare Turnstile.

Set the new password

Send POST to the full URL received, with the fields in the form body. The new password never goes in the URL, and other methods are rejected with 405:

Field	Description
`p`	PIN or code required by the flow.
`z`	New password.

read -r -s -p 'PIN: ' CHANGE_PIN; printf '\n'
read -r -s -p 'New password: ' NEW_PASSWORD; printf '\n'

curl -i -X POST \
  --data-urlencode "p=$CHANGE_PIN" \
  --data-urlencode "z=$NEW_PASSWORD" \
  "$CHANGE_URL"

Expected result: a 200 response with status 0. The user now signs in with the new password.

Warning

The link already contains the identification and validity parameters, which are validated together with the new password. Use the full link issued for that user and that operation; it expires.

Full contracts in Reference: Authentication.

Session and logout