sinch-rest-api v0.0.20

Sinch HTTP Rest API module

Node module to make Sinch REST requests from within Node or Web applications (using Browserify).

Installing

Install is straight forward using npm;

npm install sinch-rest-api --save

Note: Module is compatible with browserify

Include module in your project

var sinchApi = require('sinch-rest-api')({
		key: 'YOUR APPLICATION_KEY', 
		secret: 'YOUR_APPLICATION_SECRET'
	});

Note: Secret is optional, but starting that way will require additional credentials to be pushed to the credential stack for most features, see samples and chapter on credential stack below.

Note: If undefined is passed as credentials, sinch-rest-api will default to the Sinch Portal application key. See chapter on credential stack for more information.

Major API's

Sinch API consists of a number of major API areas, they're all reached from the same instance:

• sinchApi.base: Sinch base API, such as retrieving instance credentials or server time
• sinchApi.calling: Sinch calling API for PSTN and data calls
• sinchApi.messaging: Sinch messaging API for IM and SMS
• sinchApi.user: Sinch user API for user management (JS Auth)
• sinchApi.verification: Sinch verification API for SMS and Flashcall verification
• sinchApi.portal: Sinch portal API for partner portal operations
• sinchApi.reporting: Sinch reporting API for statistics and CDR retrieval

Within each there are a number of methods that can be used. These are defined in the papi folder.

Making REST call

Please see the official documentation for information on the available REST endpoints and data expected. You can also get a clue in the definition files found in papi folder, however, quite often the endpoint may require certain data, in these cases please refer to the REST documentation or the sample apps. REST documentation is available for Voice, SMS and Verification

All Sinch API methods returns a promise, which will be resolved for any HTTP response code between 200 and 299 but rejected for all other http codes. In both the case of a resolve and reject the data is passed back as a parsed Javascript object (if possible), otherwise it will be returned as a string. Sinch REST API module relies on the Q library for promises.

Example

Application signed REST requests

var sinchApi = require('sinch-rest-api')({
		key: 'YOUR_APPLICATION_KEY', 
		secret: 'YOUR_APPLICATION_SECRET'
	}); 

sinchApi.messaging.sendSms({number: '+1555123456', message: 'Hello World!'})
	.then(console.log)
	.fail(console.log)

The module sinch-rest-api is configured with application key and application secret. This allows for application signed requests, which are typically made from a server/backend (never a client).

Using the sendSms() method in messaging API, we can pass an object containing a number and message to send a text message. The method returns a promise which can be used to take action when the SMS has been sent. In this example, it will simply log to the console on success or fail.

Instance signed REST requests

var sinchApi = require('sinch-rest-api')(); 

var ticket = 'Some ticket, might be from sinch-ticketgen or sinchApi.user.authenticate';
// Note: Using sinchApi.user.authenticate requires both key and secret

sinchApi.base.getInstance(ticket) // Retrieve instance using a ticket
	.then(sinchApi.pushInstance.bind(sinchApi)) // Push instance to credential stack
	.then(sinchApi.calling.getConfiguration) // Retrieve call config for particular user
	.then(console.log)
	.fail(console.log)

When performing acts as a client, or a user, of your application, requests are typically signed using the "instance credentials", which, just like the application credentials, is a key/secret pair. In order to use the REST Api with Instance signed requests, you must first obtain the instance credentials. In order to obtain an instance, a ticket is required, which contains data about the user, how long it's valid, the TTL on the created instance and a signature generated using the application key/secret credentials.

This allow clients to authenticate as a particular user without exposing the application secret to anyone.

A ticket can be generated using the node package sinch-ticketgen, or it can be generated by Sinch servers if JS Auth is enabled. There are some risks with JS Auth, such as lack of control who create accounts, which is why it's recommended to always rely on making tickets in your infrastructure.

Please see documentation in sinch-ticketgen on how to use this module to generate tickets.

Credential stack

The sinchApi module utilize a stack for credentials, on which new credentials can be pushed when authenticated or popped when not needed any longer.

When creating the sinchApi object, the initial (or root) credentials can be passed. These may be an application key/secret pair, only the application key, nothing for default partner management or it can even be a user instance.

When having root credentials without a secret, the methods possible to use are limited to retrieving an instance using a ticket, or authenticating/creating users if "JS Auth" is enabled and retrieving a ticket which can be used to start an instance. This is useful for client applications. However, it should be noted that it's beneficial to have "JS Auth" turned off and instead generate the ticket on your backend.

Authenting, or creating, a user will result in a ticket, which can be used to create an instance. If this instance is to be used in future requests it must be pushed onto the credential stack. When the instance is no longer needed, it should be popped from the stack, returning sinchApi into a state to use the previous credentials.

This allows for great flexibility, for example a scenario where your root credential is the default partner management credentials, you authenticate with your sinch.com account, enabling you to make requests on behalf of you. With the new credentials you can, for example, purchase DID's or perhaps retrieve a list of applications and for each application push / pop the application key/secrets to make requests as that application (e.g. sending an SMS). You can also authenticate as a particular user and push those credentials on top of the stack to act as that user until you pop back.

There are two methods for managing the credential stack:

• sinchApi.pushInstance(credentials) Push new credentials on top of stack
• sinchApi.popInstance() Pop top credentials off of stack

Initiating sinchApi with empty credentials, sinch-rest-api will default to the default partner management credentials, allowing you to manage your partner account.

var sinchApi = require('sinch-rest-api')(); 

Feedback

Questions and/or feedback on this module can be sent by contacting dev@sinch.com.

License

The MIT License (MIT)

Copyright (c) 2017 Sinch AB

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.