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

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.