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.
@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
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
Use this part of the readme to understand what this backend sample does and how it fits in with your own backend.
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.
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"
}
]
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"
}
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"
}
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"
}
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"
}
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"
}