SECRETS

A secret facilitates an Bearer token authentication method (i.e. OAuth2) that is consumed in builtin web-hooks and with application connectors such as Salesforce.

While Secrets for application connectors are created automatically, secrets for Web-hooks are required to be created manually. This is a guide for manually creating and testing your secret integration.

Secret types

Select the type that matches the service you connect to:

Type	Used for
General - username and password	Token servers that accept a user name and password
General - username and password (v2)	The same, with the scope sent as a plain comma-separated list
Microsoft Graph REST API v1.0	Microsoft services that accept a client ID and client secret
Scanovate BTR v3.7.5	CIV identity verification
Simasti SMS	The Simasti SMS provider

Secret types used by application connectors, such as Salesforce, are created automatically and are not listed here.

After saving a secret, click Test to check that Cellosign can obtain a token with it.

General username and password

Parameter	Value
Type	Select General - username and password
url	Insert URL to post token request
Grant type	Enter the grant type
Scope	insert scope values
User name	Insert username
Password	Insert password

Request example

With the example above this is how the request from Cellosign looks like

username=Myusername&password=Mypassword&grant_type=password&scope=%28%27read%2Cwrite%27%2C%29

Expected response

Cellosign expects at least two parameters in response:

{
  "expires_in": 300,
  "access_token": "BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F"
}

• “access_token” that will be used in web hook request header for Authorization
• “expires_in” is a lapse time, in seconds, that the access token can be used before it is expired

Microsoft Graph Rest API

Parameter	Value
Type	Select Microsoft Graph REST API v1.0
url	Insert URL to post token request
Grant type	Enter the grant type
Scope	insert scope values
client_id	Insert client id
client_secret	Insert secret

Request example

client_id=8e17edb9-0f05-46cc-8741-a937e351e631&client_secret=Mysecret&scope=read%2Cwrite&grant_type=password

Expected response

Cellosign expects at least two parameters in response:

{
  "expires_in": 300,
  "access_token": "BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F"
}

• “access_token” that will be used in web hook request header for Authorization
• “expires_in” is a lapse time, in seconds, that the access token can be used before it is expired

General - username and password (v2)

Works like General - username and password, but the scope is sent as a plain comma-separated list. The original type keeps its older scope format for existing integrations; for a new integration, use v2 unless your token server expects the older format.

Parameter	Value
Type	Select General - username and password (v2)
url	Insert URL to post token request
Grant type	Enter the grant type
Scope	Insert scope values
client_id	Insert username (sent as username)
client_secret	Insert password (sent as password)

Request example

username=Myusername&password=Mypassword&grant_type=password&scope=read%2Cwrite

The expected response is the same as for General - username and password.

Scanovate BTR v3.7.5

Use this type for CIV identity verification with Scanovate BTR.

Parameter	Value
Type	Select Scanovate BTR v3.7.5
url	Insert the Scanovate token URL
Grant type	Not used for this type. The form requires a value; enter any value, e.g. client_credentials
Scope	Leave empty (not used)
client_id	Insert the client ID of your Scanovate account
client_secret	Insert the client secret of your Scanovate account

The token URL must start with https:// and resolve to a public internet address.

Request example

Unlike the other types, the request is sent as JSON (Content-Type: application/json):

{
  "client_id": "MyClientId",
  "client_secret": "MySecret"
}

The expected response is the same as for General - username and password.

Simasti SMS

Use this type for the Simasti SMS provider. For the fields and the setup steps, see Create the Simasti credential on the SMS page.

Notes and gotchas

1. Note the difference in SCOPE parameter value between the two methods.
2. Cellosign will use token until the time of expiration provided for token request. When token is expired, Cellosign will initiate a request for a new token.
3. If the response has no expires_in, Cellosign uses the token for 3500 seconds (about one hour).