FSA Quick Guide

Get it here: latest FSA-SDK

• You find runnable example(s) in the “examples” directory
• composer.json
• A ReadMe file with help for the SDK
• Examples directory
• OpenAPI directory
  • contains the fsa_openapi3.json file. The same can be found in the docs with a swagger-like representation.

• We used PHP 8.2 and the ones below. These will work with the examples. You are not obliged to use the same ones. And even if you use a different programming language you can still learn how to use our FSA-API through the PHP code.
  • guzzlehttp/guzzle
  • lcobucci/jwt

“JSON Web Tokens are an open, industry standard RFC 7519 (https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties. JWT.IO allows you to decode, verify and generate JWT.” from https://jwt.io/

The JSON Web Token (JWT) is used to manage the authentication and rules of connection to the FSA. You can access the data by decoding the bearer-token you received after a successful authentication. Therein lies the information about when the JWT token has been created, when it expires and how the signature has been signed. The token expires after 30 minutes, you can check that with the isExpire() function, then you will need to use the refresh token to conitnue or to freshly authenticate again to get the new bearer token and a refresh token to work with. See an example below with the header information containing the algo = algorithm used for the signature signing and the following fields:

• “iss” (Issuer) Claim
• “aud” (Audience) Claim
• “jti” (JWT ID) Claim
• “iat” (Issued At) Claim
• “nbf” (Not Before) Claim
• “exp” (Expiration Time) Claim
• “uniq_id” (Unique ID) Fairgate-Claim

// Header
{
  "typ": "JWT",
  "alg": "ES512"
}
// Payload
{
  "iss": "https://fsa.fairgate.ch/",
  "aud": "https://fsa.fairgate.ch/",
  "jti": "6486e32b782d2",
  "iat": 1686561579.49221,
  "nbf": 1686561579.49221,
  "exp": 1686565179.49221,
  "uniq_id": "c8af7241d59aa941c05ff7981ea0732e485ffe7469351f2a"
}

You can find more information on the following webpages:

• https://jwt.io/ (here you can decode a bearer token for preview/debugging and verify the signature)
• https://datatracker.ietf.org/doc/html/rfc7519

You can check the expiration date to know when the token has to be refreshed but you will also be informed when it expired and can then trigger the refreshing of the token with the .../auth/token/refresh call.

The JWT doesn’t need to be decoded and filled manually by you, but you can decide to want to validate the signature that was signed by Fairgate to ensure that the data you received hasn’t been tampered with (for ex with a man in the middle attack). SSL/TLS encryption of the transport alone can’t ensure that. But this step is optional and is entirely at your own discretion to use or not.

• SimpleREST.php
  • Example showing an authentication call and a subsequent call for basefields
• HttpRequests directory
  • Contains the env and request file that you can use in your favourite IDE to make requests from there.
  • FSAPI Server.Collection V 1.0.json + FG-FSA-API_UAT.postman_environment.json to use with Postman if you prefer that tool for testing the API.
• Explaining the processes of how to call the API
  • Which calls to make in which order? With which keys/token?
  • Example requests within the .http file and the Postman JSONs
  • Which and when do keys/tokens expire and what to do?

A collection of various tips and tricks to help you with the SDK and the API.

Since version 1.1 of the FSA API we support Brotli compression. This can be used to reduce the size of the data transmissions considerably (10-20% smaller than Gzip). You can use it by setting the Accept-Encoding header to “br” in your requests. The server will then respond with the Brotli compressed data if it is supported by the client. If not, it will fall back to Gzip or uncompressed data. You can check the response header Content-Encoding to see if the response is compressed and with which algorithm.

• Article on using Brotli: https://www.fastfwd.com/improve-http-compression-with-brotli/