Versions Compared

Old Version 5

changes.mady.by.user Tobias Haeberle

Saved on

compared with

New Version 6

changes.mady.by.user Tobias Haeberle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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}

Info

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:

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

    Code Block
    languagejson
    {
    "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-----"
}

  2. 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:

    Code Block
    languagejson
    {
  "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.

  3. Sign the JWT with the private key (i.e. value corresponding to the privateKey field of your account_info.json file).

Note

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

  1. Java - Using auth0/java-jwt

    Code Block
    languagejava
    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);