Authentication

To access any of the Bookiply Channel API endpoints, the call has to include a Bearer Token in the Authorization header. The payload of the Bearer Token must be a valid, shortlived JSON Web Token as explained below.

JSON Web Token

JSON Web Token (JWT, pronounced “jot”) is an open standard used to securely represent claims between two servers. If you are curious about the standard, you can read more about it here: RFC 7519.

Request Headers

For sending API requests accurately and securely, it is important to ensure that API request headers are correctly defined.

Header	Example	Description
`Accept`	`application/json`	Indicates the format to be received
`Authorization`	`Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTU1NjY0MjQ0MDAwMCJ9.eyJpc3MiOiJORVdfUEFSVE5FUiIsImlhdCI6MTUxMTkwMDAwMCwiZXhwIjoxNTExOTAzNjAwfQ.blyQtcTVqpO2hczPACba5K4C8uJUq7Lhn5FsjJCAxHqcMeJWvG_ELXwBBM_0MHipih14lLdY7N4KYFL1Bvdeug`	Bearer Token Authentication with the format `Bearer {JWT_TOKEN}`

The token used in Authorization header value is an example. You can visualize the content of the token by going to jwt.io website.

Authentication Token

For creating the signed JWT you can perform these steps:

After completing the onboarding, you will have received a JSON file named account_info.json.
Structure of account_info.json
PEM Format Key

{
    "keyId": "123e4567-e89b-12d3-a456-556642440000",
    "issuer": "NEW_PARTNER",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgevZzL1gdAFr88hb2\nOF/2NxApJCzGCEDdfSp6VQO30hyhRANCAAQRWz+jn65BtOMvdyHKcvjBeBSDZH2r\n1RTwjmYSi9R/zpBnuQ4EiMnCqfMPWiZqB4QdbAd0E7oH50VpuZ1P087G\n-----END PRIVATE KEY-----",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END PUBLIC KEY-----"
}

Using any standard JWT library in the language of your choice, you can create a JWT with a header and payload like the following example:
```
{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "123e4567-e89b-12d3-a456-556642440000"
}
{
  "iss": "NEW_PARTNER",
  "iat": 1511900000,
  "exp": 1511903600
}
```
1. Please set alg (Algorithm) as ES256
2. For the kid (Key ID) field in the header, specify the value corresponding to the keyId field of your account_info.json file.
3. For the iss (Issuer) field, specify the value corresponding to the issuer field of your account_info.json file.
4. For the iat (Issued At) field, specify the Unix time when the token was issued.
5. For the exp (Expiration Time) field, specify the Unix time denoting when the token will expire. The tokens will be rejected if the validity(i.e. exp - iat) of the token is more than 1hr.
Sign the JWT with the private key (i.e. value corresponding to the privateKey field of your account_info.json file).

Protect the privacy of your private key and signed tokens

Your private key (account_info.json) is a secret value similar to a password or API key. Store it in a secure way and follow best practices of injecting secrets into your application at runtime. Never distribute the private key alongside your application and protect access to it appropriately.

Never share signed JWTs with third parties.

Examples

Java - Using auth0/java-jwt

PrivateKey privateKey = //Get the private key instance
Algorithm algorithm = Algorithm.ES256(null, privateKey);
String signedJwt = JWT.create()
    .withKeyId(keyId) // `kid`
    .withIssuer("NEW_PARTNER") // `iss`
    .withIssuedAt(new Date(now)) // `iat`
    .withExpiresAt(new Date(now + 3600 * 1000L)) // `exp`
    .sign(algorithm);