Virgil Nexmo Demo Chat API v2 Sample Backend

Application API server for the Virgil Nexmo In-app Messaging Demo app. Its primary purpose is to register users' Virgil Cards on Virgil's Cards service and generate JWTs for users to access Nexmo and Virgil APIs. This server is intended for demonstration purposes only, it does not implement request authentication strategy. Feel free to implement your own auth tech and/or copy the code into your own backend.

Contents

• Deployment
  • Pre-requisites
  • Setup instructions
• Endpoints
  • POST /users
  • GET /users
  • POST /conversations
  • PUT /conversations
  • GET /nexmo-jwt
  • GET /virgil-jwt
• Errors

Deployment

Pre-requisites

• Ensure you have Node.js >= 8 installed
• Create a free Virgil Security account
• Create a free Nexmo account
• Install the Nexmo CLI (note the @beta tag):

  npm install -g nexmo-cli@beta

  Setup the CLI to use your Nexmo API Key and API Secret. You can get these from the settings page in the Nexmo Dashboard.

  nexmo setup api_key api_secret

Setup instructions

• Clone this Node sample server repo to your disk and step into the project's folder

  git clone https://github.com/VirgilSecurity/demo-nexmo-chat-server.git
  cd demo-nexmo-chat-server

• Create a Nexmo Application

  nexmo app:create "My Stitch App" https://example.com/answer https://example.com/event --type=rtc --keyfile=private.key

• Install the Virgil Node sample server package and run setup. The set setup will ask you a few questions...

  npm install
  npm run setup

• To provide the first input, create an END-TO-END ENCRYPTION Application in the Virgil Security Dashboard and copy the APP ID here:

  ? Enter your Virgil Security Application ID [paste Virgil APP ID here]

• Go back to the Virgil Dashboard API Keys page and create one, it will be copied to your clipboard.

  ? Enter your Virgil Security API Key private key [paste it here]

• Now, on the Virgil API keys page, find your new API key in the list and copy its API KEY ID.

  ? Enter your Virgil Security API Key ID [paste it here]

• Get your Nexmo API keys and complete the rest of the questions:

  ? Enter the path to your Nexmo app conifg file (.nexmo-app) [simply hit enter]
  ? Enter your Nexmo API Key [paste your Nexmo API key]
  ? Enter your Nexmo API Secret [paste your Nexmo API secret]

• Now the Virgil node backend server is ready to start:

  npm start

• You can test it at http://localhost:3000

Leave the server running and continue your mobile app setup: Android iOS & JS coming soon

Endpoints

Use this part of the readme to understand what this backend sample does and how it fits in with your own backend.

POST /users

An endpoint to register new user. Expects a Raw Card in base64 string form as its only parameter. The raw card must have unique identity, attempt to register a card with duplicate identity will result in 400 BadRequest error.

Request

{
    "raw_card_string": "eyJjb250ZW50X3NuYXBzaG90IjoiZXlKcFpHVnVkR2...k9In19fQ=="
}

Response

If request is successful, an object representing a Nexmo user is returned along with the base64 string representation of the user's Virgil Card and two JWTs for Nexmo and Virgil APIs:

Request must include Content-Type: "application/json" header

{
    "user": {
        "id": "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "href": "http://conversation.local/v1/users/USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "virgil_card": "eyJjb250ZW50X3NuYXBzaG90IjoiZXlKcFpHVnVkR2...k9In19fQ=="
    },
    "nexmo_jwt": "xxxxx.yyyyy.zzzzz",
    "virgil_jwt": "qqqqq.bbbbb.ddddd"
}

You can then use the CardManager from virgil sdk to import a Virgil Card from this string. The nexmo_jwt and virgil_jwt can be used to initialize the appropriate API client.

GET /users

An endpoint to retrieve a list of users.

Response

[
    {
        "name": "Dillon",
        "id": "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "href": "http://conversation.local/v1/users/USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
]

POST /conversations

An endpoint to create a new Nexmo Conversation

Request

{
    "display_name": "My new conversation" 
}

Response

{
    "id": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "href": "http://conversation.local/v1/conversations/CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

PUT /conversations

An endpoint to add a user to a conversation.

Request

{
    "conversation_id": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "user_id": "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "action": "join"
}

Parameter action must be "join" to add the user to the conversation. Other types of actions - TBD.

Response

{ 
    "id": "MEM-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "user_id": "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "state": "JOINED",
    "timestamp": { "joined": "2018-01-15T15:17:59.248Z" },
    "channel": { "type": "app" },
    "href": "http://conversation.local/v1/conversations/CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab/members/MEM-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

GET /nexmo-jwt?identity=[YOUR_USER_IDENTITY]

An endpoint to obtain an access token for the Nexmo API. The URL must include a query parameter named identity that is the identity of the user to issue the token for.

Response

{
    "jwt": "xxxxx.yyyyy.zzzzz"
}

GET /virgil-jwt

An endpoint to obtain an access token for the Virgil Security API. The URL must include a query parameter named identity that is the identity of the user to issue the token for.

Response

{
    "jwt": "qqqqq.bbbbb.ddddd"
}

Errors

Application uses standard HTTP response codes:

200 - Success
400 - Request error
500 - Server error

Additional information about the error is returned in response body as JSON object:

{
    "status": 500,
    "error_code": 50000,
    "message": "Message containing error details"
}