Authentication

Base URL

https://office.rivenapp.com/api/v1

1. User Registration

a. Submit user phone number

Endpoint:

POST /auth/enter-phone

Description: Submit user phone number to initiate OTP ownership verification & authentication.

Headers:

Key	Value
Content-Type	application/json

Request Body:

{
    "phone": "+254XXXXXXXXX"
}

Response:

{
    "message": "Confirmation code sent",
    "status": true
}

b. Confirm registration code

{danger} SMS works with Airtel and Telkom numbers only for now

Endpoint:

POST /auth/confirm-code

Description: Submit user phone number to initiate OTP ownership verification & authentication.

Headers:

Key	Value
Content-Type	application/json

Request Body:

{
    "phone": "+254XXXXXXXXX",
    "code": "439559"
}

Response:

1. Success

   {
   "message": "Code verified",
   "auth": {
       "type": "Bearer",
       "token": "2|IpYUwCNc1nWXlgAOX6oS87Ogj0BRVAKhFZrtJHu1742ff30a"
   },
   "status": true
   }

2. Error

   {
   "message": "Invalid code",
   "auth": [],
   "status": false
   }

c. Complete registration

Endpoint: POST /account/create

Description: Complete new trader's registration with the Riven trading app.

Headers:

Key	Value
Content-Type	application/json
Authorization	Bearer {your_token}

Request Body:

{
  "contact": {
    "email_address": "user1@rivenapp.com",
    "phone_number": "+254XXXXXXXXX",
    "street_address":"New Kanairo",
    "city": "San Majei",
    "state": "CA",
    "postal_code": "34401"
  },
  "identity": {
    "given_name": "User",
    "family_name": "One",
    "date_of_birth": "1980-01-01",
    "tax_id": "234-11-1234",
    "tax_id_type": "USA_SSN",
    "country_of_citizenship": "USA",
    "country_of_birth": "USA",
    "country_of_tax_residence": "USA",
    "funding_source": "employment_income",
    "visa_type": null,
    "visa_expiration_date": null,
    "date_of_departure_from_usa": null,
    "permanent_resident": null,
    "is_force_finra_institutional": null,
    "investment_experience_with_stocks": null,
    "investment_experience_with_options": null,
    "investment_time_horizon": null
  },
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": false,
    "is_affiliated_exchange_or_iiroc": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false,
    "is_discretionary": null
  },
  "agreements": {
      "agreement": "customer_agreement",
      "signed_at": "2024-10-28T14:05:05.818716163Z",
      "ip_address": "127.0.0.1"
   },
   "documents": {
      "document_type": "identity_verification",
      "document_sub_type": "passport",
      "content": "/9j/4AAQS+iiigD//2Q==",
      "content_data": null,
      "mime_type": "image/jpeg"
    },
  "trusted_contact": {
    "given_name": "Bazu",
    "family_name": "Baite",
    "email_address": "bazu.baite@example.com"
  },
  "minor_identity": null,
  "entity_id": null,
  "additional_information": "",
  "account_type": "",
  "account_sub_type": null,
  "auto_approve": null,
  "beneficiaries": null,
  "trading_configurations": null,
  "currency": null,
  "enabled_assets": null,
  "instant": null,
  "entity_identity": null,
  "entity_contact": null,
  "authorized_individuals": null,
  "ultimate_beneficial_owners": null,
  "sub_correspondent": null
}

Response:

{
    "data": {
        "id": 1,
        "phone": "+254XXXXXXXXX",
        "otp_code": null,
        "name": "User One",
        "first_name": "User",
        "last_name": "One",
        "profile_photo": null,
        "email": "user1@rivenapp.com",
        "email_verified_at": null,
        "other_phones": null,
        "dob": "1979-12-31T21:00:00.000000Z",
        "gender": null,
        "alpaca_account_id": "bbe3ef5a-8a99-44b4-acbf-0b933a0c9978",
        "account_status": "new",
        "created_at": "2024-11-02T06:33:08.000000Z",
        "updated_at": "2024-11-02T07:18:29.000000Z"
    },
    "status": true
}

2. User Login

a. Send login code

Endpoint:

POST /login/send-code

Description: This endpoint allows users to log in using their phone number. A confirmation code will be sent to the user's phone number.

Headers:

Key	Value
Content-Type	application/json

Request Body:

{
    "phone": "+254XXXXXXXXX"
}

Response:

{
    "message": "Login code sent",
    "status": true
}

b. Verify code & login

Endpoint:

POST /login/verify-code

Description: Log in the trader and generate an API OAuth2.0 token if OTP code is valid

Headers:

Key	Value
Content-Type	application/json

Request Body:

{
    "phone": "+254XXXXXXXXX",
    "code": "42441"
}

Response:

1. Success

{
    "user": {
        "id": 1,
        "phone": "+254XXXXXXXXX",
        "otp_code": null,
        "name": "User One",
        "first_name": "User",
        "last_name": "One",
        "profile_photo": null,
        "email": "user1@rivenapp.com",
        "email_verified_at": null,
        "other_phones": null,
        "dob": "1979-12-31T21:00:00.000000Z",
        "gender": null,
        "alpaca_account_id": "bbe3ef5a-8a99-44b4-acbf-0b933a0c9978",
        "account_status": "new",
        "created_at": "2024-11-02T06:33:08.000000Z",
        "updated_at": "2024-11-02T07:33:09.000000Z"
    },
    "auth": {
        "type": "Bearer",
        "token": "2|Ck6eTMeJvq1prFCWvK3zmfyHxK1XpWh84ScTOufh1a2d9c19"
    },
    "status": true
}

2. Error

{
    "message": "Invalid credentials",
    "status": false
}

3. Logout

Endpoint

POST /logout

Description

This endpoint logs out the authenticated user by revoking their bearer token.

Request Headers

Key	Value
Authorization	Bearer {your_token}
Content-Type	application/json

Response

{
    "message": "Successfully logged out"
}