Authorization

Introduction OAuth 2.0 Autonomous Pin Request a pin Request a delegation token

Accounts

Entities

User accounts

Groups Files Folders Templates Email templates Apps Errors

Pin based authentication

Using this technique, the user inputs a PIN code into your application using an out-of-band technique.

Typically, the user is presented with the PIN from the SmartVault web server and performs a copy and paste operation to put the PIN into your application. Your application exchanges the PIN code for an access token.

Pin numbers are specific to each application authorized by each user.

Request a pin

For each user who uses your application, you will need to have SmartVault generate a pin for your user.

The pin is used to authenticate each API call, and only needs to be generated once for each user.

The pin is not directly returned to your application. Instead, you will get a unique URL that the user will need to visit in order to authorize your application in SmartVault. The user will be given their pin number, which they will need to enter into your application so you can authenticate with SmartVault.

This call is used to request a pin from SmartVault. It returns a URL for the user to visit to authorize the request and retrieve their pin.

POST/pin/end

Body parameters

client_idstringThe client ID as registered in SmartVault.

{
    "client_id": "SampleCRMWeb"
}

Request

Headers:
Content-Type:application/json
Accept:application/json
Body:
{
  "client_id": "SampleCRMWeb"
}

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{ \"client_id\": \"SampleCRMWeb\" }" \
'https://rest.smartvault.com/pin/end'

// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;
Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  \"client_id\": \"SampleCRMWeb\"}");
Response response = client.target("https://rest.smartvault.com/pin/end")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Accept", "application/json")
  .post(payload);
System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

var request = new XMLHttpRequest();
request.open('POST', 'https://rest.smartvault.com/pin/end');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};
var body = {
  'client_id': 'SampleCRMWeb'
};
request.send(JSON.stringify(body));

$ENV{'PERL_LWP_SSL_VERIFY_HOSTNAME'} = 0;
use LWP::UserAgent;
use strict;
use warnings;
use 5.010;
use Cpanel::JSON::XS qw(encode_json decode_json);
my $ua   = LWP::UserAgent->new;
my $data = '{  "client_id": "SampleCRMWeb"}';
$ua->default_header("Content-Type" => "application/json");
$ua->default_header("Accept" => "application/json");
my $response = $ua->post("https://rest.smartvault.com/pin/end", Content => $data);
print $response->as_string;

$ENV{'PERL_LWP_SSL_VERIFY_HOSTNAME'} = 0;
use LWP::UserAgent;
use strict;
use warnings;
use 5.010;
use Cpanel::JSON::XS qw(encode_json decode_json);
my $ua   = LWP::UserAgent->new;
my $data = '{  "client_id": "SampleCRMWeb"}';
$ua->default_header("Content-Type" => "application/json");
$ua->default_header("Accept" => "application/json");
my $response = $ua->post("https://rest.smartvault.com/pin/end", Content => $data);
print $response->as_string;

from urllib2 import Request, urlopen
values = """
  {
    "client_id": "SampleCRMWeb"
  }
"""
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}
request = Request('https://rest.smartvault.com/pin/end', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://rest.smartvault.com/pin/end");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"client_id\": \"SampleCRMWeb\"
}");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Accept: application/json"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
  "client_id": "SampleCRMWeb"
}'
headers = {
  :content_type => 'application/json',
  :accept => 'application/json'
}
response = RestClient.post 'https://rest.smartvault.com/pin/end', values, headers
puts response

package main
import (
	"bytes"
	"fmt"
	"io/ioutil"
	"net/http"
)
func main() {
	client := &http.Client{}
	body := []byte("{\n  \"client_id\": \"SampleCRMWeb\"\n}")
	req, _ := http.NewRequest("POST", "https://rest.smartvault.com/pin/end", bytes.NewBuffer(body))
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Accept", "application/json")
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Errored when sending request to the server")
		return
	}
	defer resp.Body.Close()
	resp_body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(resp.Status)
	fmt.Println(string(resp_body))
}

//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://rest.smartvault.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
  
  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
  
    using (var content = new StringContent("{  \"client_id\": \"SampleCRMWeb\"}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("pin/end", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}

Dim request = TryCast(System.Net.WebRequest.Create("https://rest.smartvault.com/pin/end"), System.Net.HttpWebRequest)
request.Method = "POST"
request.ContentType = "application/json"
request.Accept = "application/json"
Using writer = New System.IO.StreamWriter(request.GetRequestStream())
  Dim byteArray As Byte() = System.Text.Encoding.UTF8.GetBytes("{
  \""client_id\"": \""SampleCRMWeb\""
}")
  request.ContentLength = byteArray.Length
  writer.Write(byteArray)
  writer.Close()
End Using
Dim responseContent As String
Using response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)
  Using reader = New System.IO.StreamReader(response.GetResponseStream())
    responseContent = reader.ReadToEnd()
  End Using
End Using

import groovyx.net.http.RESTClient
import static groovyx.net.http.ContentType.JSON
import groovy.json.JsonSlurper
import groovy.json.JsonOutput
@Grab (group = 'org.codehaus.groovy.modules.http-builder', module = 'http-builder', version = '0.5.0')
def client = new RESTClient("https://rest.smartvault.com")
def emptyHeaders = [:]
emptyHeaders."Content-Type" = "application/json"
emptyHeaders."Accept" = "application/json"
def jsonObj = new JsonSlurper().parseText('{
  "client_id": "SampleCRMWeb"
}')
response = client.post( path : "/pin/end",
                        body : jsonObj,
                        headers: emptyHeaders,
                        contentType : JSON )
println("Status:" + response.status)
if (response.data) {
  println("Content Type: " + response.contentType)
  println("Body:\n" + JsonOutput.prettyPrint(JsonOutput.toJson(response.data)))
}

NSURL *URL = [NSURL URLWithString:@"https://rest.smartvault.com/pin/end"];
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:URL];
[request setHTTPMethod:@"POST"];
[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
[request setValue:@"application/json" forHTTPHeaderField:@"Accept"];
[request setHTTPBody:[@"{\n  \"client_id\": \"SampleCRMWeb\"\n}" dataUsingEncoding:NSUTF8StringEncoding]];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *task = [session dataTaskWithRequest:request
                                        completionHandler:
                              ^(NSData *data, NSURLResponse *response, NSError *error) {
                                  if (error) {
                                      // Handle error...
                                      return;
                                  }
                                  if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
                                      NSLog(@"Response HTTP Status code: %ld\n", (long)[(NSHTTPURLResponse *)response statusCode]);
                                      NSLog(@"Response HTTP Headers:\n%@\n", [(NSHTTPURLResponse *)response allHeaderFields]);
                                  }
                                  NSString* body = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                                  NSLog(@"Response Body:\n%@\n", body);
                              }];
[task resume];

import Foundation
// NOTE: Uncommment following two lines for use in a Playground
// import PlaygroundSupport
// PlaygroundPage.current.needsIndefiniteExecution = true
let url = URL(string: "https://rest.smartvault.com/pin/end")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.httpBody = """
"{\n  \"client_id\": \"SampleCRMWeb\"\n}"
""".data(using: .utf8)
let task = URLSession.shared.dataTask(with: request) { data, response, error in
  if let response = response {
    print(response)
    if let data = data, let body = String(data: data, encoding: .utf8) {
      print(body)
    }
  } else {
    print(error ?? "Unknown error")
  }
}
task.resume()

Response

Returns the authorization uri.

Show success object

Will return an error object if the client id is not specified in the request body.

Request a delegation token

If you are using pin-based authentication, you will need the user's pin in order to get a delegation token.

No "Authorization" header is required.

This call is used to request a delegation token. This is the token you will use to authenticate each time your application makes a call to the API.

POST/pin/auth

Body parameters

user_emailstringThe user account's email address.

client_idstringThe client ID as registered in SmartVault.

pinstring (optional)The pin number assigned to the email and client ID. This is used only for pin-based authentication.

{
  "user_email": "testuser@smartvault.com",
  "pin_info": {
    "client_id": "SampleCRMWeb",
    "pin": 341450484
  }
}

Request

Headers:
Content-Type:application/json
Accept:application/json
Body:
{
  "user_email": "testuser@smartvault.com",
  "pin_info": {
    "client_id": "SampleCRMWeb",
    "pin": 341450484
  }
}

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"user_email\": \"testuser@smartvault.com\",
    \"pin_info\": {
        \"client_id\": \"SampleCRMWeb\",
        \"pin\": 341450484
    }
}" \
'https://rest.smartvault.com/pin/auth'

// Maven : Add these dependecies to your pom.xml (java6+)
// <dependency>
//     <groupId>org.glassfish.jersey.core</groupId>
//     <artifactId>jersey-client</artifactId>
//     <version>2.8</version>
// </dependency>
// <dependency>
//     <groupId>org.glassfish.jersey.media</groupId>
//     <artifactId>jersey-media-json-jackson</artifactId>
//     <version>2.8</version>
// </dependency>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;
Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  \"user_email\": \"testuser@smartvault.com\",  \"pin_info\": {    \"client_id\": \"SampleCRMWeb\",    \"pin\": 341450484  }}");
Response response = client.target("https://rest.smartvault.com/pin/auth")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Accept", "application/json")
  .post(payload);
System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

var request = new XMLHttpRequest();
request.open('POST', 'https://rest.smartvault.com/pin/auth');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};
var body = {
  'user_email': 'testuser@smartvault.com',
  'pin_info': {
    'client_id': 'SampleCRMWeb',
    'pin': 341450484
  }
};
request.send(JSON.stringify(body));

var request = require('request');
request({
  method: 'POST',
  url: 'https://rest.smartvault.com/pin/auth',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: "{  \"user_email\": \"testuser@smartvault.com\",  \"pin_info\": {    \"client_id\": \"SampleCRMWeb\",    \"pin\": 341450484  }}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

$ENV{'PERL_LWP_SSL_VERIFY_HOSTNAME'} = 0;
use LWP::UserAgent;
use strict;
use warnings;
use 5.010;
use Cpanel::JSON::XS qw(encode_json decode_json);
my $ua   = LWP::UserAgent->new;
my $data = '{  "user_email": "testuser@smartvault.com",  "pin_info": {    "client_id": "SampleCRMWeb",    "pin": 341450484  }}';
$ua->default_header("Content-Type" => "application/json");
$ua->default_header("Accept" => "application/json");
my $response = $ua->post("https://rest.smartvault.com/pin/auth", Content => $data);
print $response->as_string;

from urllib2 import Request, urlopen
values = """
  {
    "user_email": "testuser@smartvault.com",
    "pin_info": {
      "client_id": "SampleCRMWeb",
      "pin": 341450484
    }
  }
"""
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}
request = Request('https://rest.smartvault.com/pin/auth', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://rest.smartvault.com/pin/auth");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"user_email\": \"testuser@smartvault.com\",
  \"pin_info\": {
    \"client_id\": \"SampleCRMWeb\",
    \"pin\": 341450484
  }
}");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Accept: application/json"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);

require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
  "user_email": "testuser@smartvault.com",
  "pin_info": {
    "client_id": "SampleCRMWeb",
    "pin": 341450484
  }
}'
headers = {
  :content_type => 'application/json',
  :accept => 'application/json'
}
response = RestClient.post 'https://rest.smartvault.com/pin/auth', values, headers
puts response

package main
import (
	"bytes"
	"fmt"
	"io/ioutil"
	"net/http"
)
func main() {
	client := &http.Client{}
	body := []byte("{\n  \"user_email\": \"testuser@smartvault.com\",\n  \"pin_info\": {\n    \"client_id\": \"SampleCRMWeb\",\n    \"pin\": 341450484\n  }\n}")
	req, _ := http.NewRequest("POST", "https://rest.smartvault.com/pin/auth", bytes.NewBuffer(body))
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Accept", "application/json")
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Errored when sending request to the server")
		return
	}
	defer resp.Body.Close()
	resp_body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(resp.Status)
	fmt.Println(string(resp_body))
}

//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://rest.smartvault.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
  
  httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
  
    using (var content = new StringContent("{  \"user_email\": \"testuser@smartvault.com\",  \"pin_info\": {    \"client_id\": \"SampleCRMWeb\",    \"pin\": 341450484  }}", System.Text.Encoding.Default, "application/json"))
    {
      using (var response = await httpClient.PostAsync("pin/auth", content))
      {
        string responseData = await response.Content.ReadAsStringAsync();
      }
  }
}

Dim request = TryCast(System.Net.WebRequest.Create("https://rest.smartvault.com/pin/auth"), System.Net.HttpWebRequest)
request.Method = "POST"
request.ContentType = "application/json"
request.Accept = "application/json"
Using writer = New System.IO.StreamWriter(request.GetRequestStream())
  Dim byteArray As Byte() = System.Text.Encoding.UTF8.GetBytes("{
  \""user_email\"": \""testuser@smartvault.com\"",
  \""pin_info\"": {
    \""client_id\"": \""SampleCRMWeb\"",
    \""pin\"": 341450484
  }
}")
  request.ContentLength = byteArray.Length
  writer.Write(byteArray)
  writer.Close()
End Using
Dim responseContent As String
Using response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)
  Using reader = New System.IO.StreamReader(response.GetResponseStream())
    responseContent = reader.ReadToEnd()
  End Using
End Using

import groovyx.net.http.RESTClient
import static groovyx.net.http.ContentType.JSON
import groovy.json.JsonSlurper
import groovy.json.JsonOutput
@Grab (group = 'org.codehaus.groovy.modules.http-builder', module = 'http-builder', version = '0.5.0')
def client = new RESTClient("https://rest.smartvault.com")
def emptyHeaders = [:]
emptyHeaders."Content-Type" = "application/json"
emptyHeaders."Accept" = "application/json"
def jsonObj = new JsonSlurper().parseText('{
  "user_email": "testuser@smartvault.com",
  "pin_info": {
    "client_id": "SampleCRMWeb",
    "pin": 341450484
  }
}')
response = client.post( path : "/pin/auth",
                        body : jsonObj,
                        headers: emptyHeaders,
                        contentType : JSON )
println("Status:" + response.status)
if (response.data) {
  println("Content Type: " + response.contentType)
  println("Body:\n" + JsonOutput.prettyPrint(JsonOutput.toJson(response.data)))
}

NSURL *URL = [NSURL URLWithString:@"https://rest.smartvault.com/pin/auth"];
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:URL];
[request setHTTPMethod:@"POST"];
[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
[request setValue:@"application/json" forHTTPHeaderField:@"Accept"];
[request setHTTPBody:[@"{\n  \"user_email\": \"testuser@smartvault.com\",\n  \"pin_info\": {\n    \"client_id\": \"SampleCRMWeb\",\n    \"pin\": 341450484\n  }\n}" dataUsingEncoding:NSUTF8StringEncoding]];
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *task = [session dataTaskWithRequest:request
                                        completionHandler:
                              ^(NSData *data, NSURLResponse *response, NSError *error) {
                                  if (error) {
                                      // Handle error...
                                      return;
                                  }
                                  if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
                                      NSLog(@"Response HTTP Status code: %ld\n", (long)[(NSHTTPURLResponse *)response statusCode]);
                                      NSLog(@"Response HTTP Headers:\n%@\n", [(NSHTTPURLResponse *)response allHeaderFields]);
                                  }
                                  NSString* body = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
                                  NSLog(@"Response Body:\n%@\n", body);
                              }];
[task resume];

import Foundation
// NOTE: Uncommment following two lines for use in a Playground
// import PlaygroundSupport
// PlaygroundPage.current.needsIndefiniteExecution = true
let url = URL(string: "https://rest.smartvault.com/pin/auth")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.httpBody = """
"{\n  \"user_email\": \"testuser@smartvault.com\",\n  \"pin_info\": {\n    \"client_id\": \"SampleCRMWeb\",\n    \"pin\": 341450484\n  }\n}"
""".data(using: .utf8)
let task = URLSession.shared.dataTask(with: request) { data, response, error in
  if let response = response {
    print(response)
    if let data = data, let body = String(data: data, encoding: .utf8) {
      print(body)
    }
  } else {
    print(error ?? "Unknown error")
  }
}
task.resume()

Response

Returns the delegation token, its expiracy and the id related to the user used for retrieving it.

Show success object

Will return an error object if any parameters are missing.

SmartVault

Pin based authentication

.css-1r0pe6c{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1r0pe6c:hover{-webkit-text-decoration:underline;text-decoration:underline;}Request a pin

Show success object

Request a delegation token

Show success object

Request a pin