First a user will sign into your external site. Once they have been authenticated, your application will construct a token (JWT) and redirect to the Deeper Signals SSO URL with this token as a query string parameter. Deeper Signals deconstructs this payload and either finds the user and signs them in, or if they don't already have an account on your Deeper Signals site, creates an account and signs them in.
The Deeper Signals SSO URL is the URL that you redirect to after a user has successfully authenticated in your system. It has the following structure:
https://app.deepersignals.com/sso/{JWT-TOKEN}
Your application must construct the JWT payload and sign it using your Deeper Signals API key. The key can be found under the API section of your Deeper Signals admin dashboard. If you don't see API options in your admin dashboard, request API permissions from your Deeper Signals account administrator. The best practice for security is to generate the JWT token on a server and then retrieve it from the client side, rather than exposing the JWT shared secret in the client-side JavaScript.
Note : Do not base 64 encode your API key when signing your JWT token. Our application expects the API key as-is when verifying your JWT token.
The JWT payload is typically constructed as a hash. The following attributes are supported:
{
"iat": 1620212314,
"exp": 1620215914,
"client_id": "6hUsd268",
"email": "user@deepersignals.com",
"first_name": "deeper",
"last_name": "Signals",
"ds_id":1,
"locale": "en",
"identity": "USHdUHi6"
}
There are various libraries for working with JWT. A list can be found here. We recommend using the HS256 algorithm.
One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don’t put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. It then base 64 encodes that string and then makes an HMAC of the base 64 string which depends on the shared secret. This produces a signature that the recipient side can use to validate the user.
The api authentication works through the api token which is sent with every authenticated request in the X-TOKEN header.
The api token will be provided by Deeper Signals to you, and is state less. In addition when requesting an api token valid redirect domains need to be provided in order for the SSO error url functionality to work.
The playbook is created via API and is used to define actions which should happen after a user is logged in or registered with an SSO link. Using the playbook you can define a couple of options like which assessments should be assigned to a user, which projects the user should join, which groups the user should be assigned.
This concept is used to minimize the number of API calls for creating a user. You create a playbook once and you use it multiple times. In that way you have no API calls when creating a user, you just use the identity of the playbook, sign the JWT token, redirect the user to our sso url and you are all set. The user is created and their assessments are assigned.
When a playbook gets created a unique identifier is created for the specific playbook. You can send that identifier as a part of the SSO JWT token payload under the identity key.
curl -X POST -d '{
"name":"TestPlaybook2",
"assessments":[{"id":230}],
"projects":[{"id":1}],
"groups":[{"name":"TestGroup"}]
}' "https://api.deepersignals.com/api/external/playbook/create"
POST /api/external/playbook/create HTTP/1.1
Host: api.deepersignals.com
{
"name":"TestPlaybook2",
"assessments":[{"id":230}],
"projects":[{"id":1}],
"groups":[{"name":"TestGroup"}]
}
Status | 200 OK |
---|---|
|
curl -X PUT -d '{
"name":"TestPlaybook3",
"assessments":[{"id":230}],
"projects":[{"id":1}],
"groups":[{"name":"TestGroup"}]
}' "https://api.deepersignals.com/api/external/playbook/{playbook_id}"
PUT /api/external/playbook/{playbook_id} HTTP/1.1
Host: api.deepersignals.com
{
"name":"TestPlaybook3",
"assessments":[{"id":230}],
"projects":[{"id":1}],
"groups":[{"name":"TestGroup"}]
}
Status | 200 OK |
---|---|
|
curl -X DELETE "https://api.deepersignals.com/api/external/playbook/{playbook_id}"
DELETE /api/external/playbook/{playbook_id} HTTP/1.1
Host: api.deepersignals.com
Status | 204 No Content |
---|
curl -X GET "https://api.deepersignals.com/api/external/playbook"
GET /api/external/playbook HTTP/1.1
Host: api.deepersignals.com
Status | 200 OK |
---|---|
|
Projects are used so you can more easily manage the users of your assessment. If a user is part of a project their results aree conveniently grouped within the same project.
curl -X GET "https://api.deepersignals.com/api/external/assessments"
GET /api/external/assessments HTTP/1.1
Host: api.deepersignals.com
Status | 200 OK |
---|---|
|
Route parameters:
Available locales
Locale | Language name |
---|---|
en | English |
it | Italian |
bg | Bulgarian |
pt-BR | Portuguese |
es-ES | Spanish |
de | German |
fr | French |
es-419 | Spanish, Latam |
curl -X GET "https://api.deepersignals.com/api/external/pdf/{userId}/{formId}/download/{locale}"
GET /api/external/pdf/{userId}/{formId}/download/{locale} HTTP/1.1
Host: api.deepersignals.com
Status | 200 OK |
---|---|
curl -X GET "https://api.deepersignals.com/api/external/users/{user_id}/results"
GET /api/external/users/{user_id}/results HTTP/1.1
Host: api.deepersignals.com
Status | 200 OK |
---|---|
|
curl -X GET "https://api.deepersignals.com/api/external/users/{user_id}"
GET /api/external/users/{user_id} HTTP/1.1
Host: api.deepersignals.com
Status | 200 OK |
---|---|
|
curl -X DELETE "https://api.deepersignals.com/api/external/users/15764"
DELETE /api/external/users/15764 HTTP/1.1
Host:https://api.deepersignals.com
Status | 204 No Content |
---|
curl -X POST -d '{
"first_name": "deeper",
"last_name": "Signals",
"locale": "en",
"email":"deeperrr@signal.com",
"groups": ["testG"]
}' "https://api.deepersignals.com/api/external/user"
POST /api/external/user HTTP/1.1
Host:
{
"first_name": "deeper",
"last_name": "Signals",
"locale": "en",
"email":"deeperrr@signal.com",
"groups": ["testG"]
}
Status | 200 OK |
---|---|
Content-Type | application/json |
|
Status | 409 Conflict |
---|---|
Content-Type | application/json |
|
curl -X GET "https://api.deepersignals.com/api/external/user/email/{email_address}"
GET /api/external/user/email/{email_address} HTTP/1.1
Host:
Status | 200 OK |
---|---|
Content-Type | application/json |
|
Status | 404 Not Found |
---|---|
Content-Type | application/json |
|
The webhook is registerd in your account settings on the Deeper Signals App. From the webhook url you can get a few type of events which you can see listed in the table below with their json payloads. Webhook settings are not enabled by default. Contact your Deeper Signals administrator to have these settings enabled.
Status | 200 OK |
---|---|
|
Status | 200 OK |
---|---|
|
Status | 200 OK |
---|---|
Note | Scales might be different on different kinds of assessments. This is an example for the Core Drivers Pro assessment. |
|
Status | 200 OK |
---|---|
|
Status | 200 OK |
---|---|
|