Overview

Description

This page describes the provisioning API for the Samoby service.
With the following requests, the Service Providing Partners easily can easily create, read, update and delete their users’ accounts.

Date format

All the dates must be in UTC following the next format: YYYY-MM-DD HH:MM:SS.UU (e.g 2018-12-14 04:25:02.818002)

SSL only

All requests must be done over SSL.

Authentication: OAuth 2.0

We use OAuth 2.0 to provide authorized access to our API.
Each Service Providing Partner, hereafter referred to as "Company", will be given a unique username and password to verify the source of the requests (client_id and client_secret).

HTTP Status Codes

Use of standard HTTP Status codes:
HTTP Status CodeDescription
200Operation Success
201Created
202Accepted
400Bad Request
403Forbidden
404Not Found
415Unsupported Media Type
500Internal Server Error

Extra info returned

For some HTTP Status Code, the API can return extra info following the JSON format:
{
	"error": {
		"code": ERROR_CODE,
		"message": "ERROR_INFO"
	}
}

The extra info that can be returned is:
HTTP Status CodeCodeDescription
403801CompanyUsername is required
403802Admin is required
403803Username for Admin is required
403804CompanyUsername already exists
403805Provisioning only available for companies
403806The Admin already exists
403807Admin email not valid
403808Invalid number of licenses
403809Admin email or telephone number is required

Authentication: OAuth 2.0

We use OAuth 2.0 to provide authorized access to our API.

Limited Token

URL:/oauth2/token
Description:Requesting a limited "access_token" enables the Company to obtain authorized access to the Provisioning API for a limited time.
Methods Allowed:POST
JSON structure:
{
	"client_id":"CLIENT_ID",
	"client_secret":"CLIENT_SECRET",
	"grant_type":"client_credentials"
}
Example response:
{
	"access_token":"XXX",
	"expires_in":1200,
	"token_type":"Bearer",
	"scope":"limited",
	"user_id":null
}

Account

The provisioning API accepts calls to create, read, update and delete an account.
The JSON format is used for an Account object:
{
	"account":{
		"companyUsername":"",	-- Required: string format
		"licenses":,		-- Optional: number of devices that the account can have linked 
		"admin":{
			"username":"",		-- Required: string format
			"email":"",		-- Optional: needed to send notifications by mail
			"telephoneNumber":"",	-- Optional: needed to send notifications by SMS
			"name":"",		-- Optional: string format
			"language":""		-- Optional: ISO 639-1 code
		},
		"creationTime":"",	-- Output value
		"deletionTime":"",	-- Output value: it will be null if the account is active
		"status":""		-- Optional: status of the account ("active" - "disabled" - "deleted")
		"product":""		-- Optional
	}
}

POST: Create Account

URL:POST /accounts
Description:Request to create an account.
"companyUsername" and "username" are required values for the Account object.
Example request:
POST /accounts
{
	"account":{
		"companyUsername":"company0001",
		"licenses":5, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		}
	}
}
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":5, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817477",
		"status":"active"
	}
}

GET: Read Account

URL:GET /accounts/companyUsername
Description:Request to retrieve the info of a specified account or all the accounts belonging to the company.
The URL can include the "companyUsername" of the account to be retrieved.
If no "companyUsername" is specified, the request will return all the accounts belonging to the company.
Example request:
GET /accounts/company0001
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":5, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817537",
		"status":"active"
	}
}
Special GET params:"includeDeleted" can be sent as a GET parameter to include the deleted accounts in the response (e.g GET /accounts/?includeDeleted).

PUT: Update licences of an Account

URL:PUT /accounts/companyUsername
Description:Request to update number of licenses of an account.
The URL must include the "companyUsername" of the account to be updated.
Example request:
PUT /accounts/company0001
{
	"account":{
		"licenses":8, 
	}
}
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":8, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817548",
		"status":"active"
	}
}

PUT: Disable Account

URL:PUT /accounts/companyUsername
Description:Request to disable an account.
The URL must include the "companyUsername" of the account to disable.
Example request:
PUT /accounts/company0001
{
	"account":{
		"status":"disabled", 
	}
}
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":8, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817554",
		"status":"disabled"
	}
}

PUT: Active Account

URL:PUT /accounts/companyUsername
Description:Request to active an account.
The URL must include the "companyUsername" of the account to enable.
Example request:
PUT /accounts/company0001
{
	"account":{
		"status":"active", 
	}
}
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":8, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817559",
		"status":"active"
	}
}

DELETE: Remove Account

URL:DELETE /accounts/companyUsername
Description:Request to remove an account.
This request will automatically unlink all the devices linked to the account.
The URL must include the "companyUsername" of the account to be updated.
Example request:
DELETE /accounts/company0001
Example response:
{
	"account":{
		"companyUsername":"company0001",
		"licenses":8, 
		"admin":{
			"username":"username0001",
			"email":"username0001@server.com"
		},
		"creationTime":"2018-12-14 04:25:02.817564",
		"deletionTime":"2018-12-14 04:25:02.817568",
		"status":"deleted"
	}
}