Introduction
Welcome to the documentation site for the official Pliance REST APIs. This guide explains the fundamentals to start accessing our services from your applications.
Security
Pliance uses secure communication over HTTPS
with server certificates for all data during transit.
Additional security can be achieved through IP-filtering and client certificates.
Authentication
Pliance.io requires bearer tokens as a mean of authentication for your HTTP requests. The client must provide the security token in the Authorization
header with each call to our API.
These security tokens can be used interchangeably from either a system or from a web browser.
Generating Security Token
We are using JSON Web Token. To generate a valid token, add the same fields as specified below and sign with your secret
.
For assistance debugging your tokens, we recommend using https://jwt.io/.
{
"typ": "JWT",
"alg": "HS256"
}
{
"iat": 1555495956,
"nbf": 1555495956,
"exp": 1555496256,
"aud": "pliance.io",
"iss": "<CUSTOMERID>",
"given_name": "<USERNAME>",
"sub": "<USERID>"
}
Property | Meaning | Description |
---|---|---|
iat | Issued At | When the token was generated (UTC) |
nbf | Not Before | Token can't be used before (UTC) |
exp | Expiration Time | Token can't be used after (UTC) |
aud | Audience | The recipient of the token, always pliance.io |
iss | Issuer | Company identifier given by us. |
given_name | Username | Name that will appear in the logs, can be either a regular user or a system user. |
sub | UserId | Id that will appear in the logs, can be either a regular user id(database id, OAuth subject) or a system user id. |
Multitenancy
By default multitenancy is not enabled in the system. Changing this setting will result in data loss and should be configured before populating the system with data. Please contact our support to enable it.
If you are running the multitenancy setup, you need to supply the HTTP-header X-Tenant
in each call, X-Tenant
is an arbitrary string that is used to isolate tenants from each other.
Example of calling the ping endpoint with a tenant called
Growth Finanical Partner
curl -H "X-Tenant: Growth Finanical Partner" "$HOST/api/Ping" -H "Authorization: Bearer $JWT"
Webhooks
A webhook enables us to push notifications from our system to yours. Make sure the URL of your registered HTTP callbacks are publicly available and required ports opened in your firewall.
If you're developing on a computer without direct access to the internet, you can use a product such as https://ngrok.com/ to create a public tunnel to a specific port on your computer.