This guide documents how to integrate the Sailing Schedules functionality onto your platform in a safe way, as well as providing the capability to track API usage by your internal customers.

In order to implement this integration, you will need:

• a valid Portcast API key that is associated with an Org that has Sailing Schedules functionality activated
• a text identifier you can provide to identify your internal customers (can be the name of the customer, for example)

Step 1: Generate a temporary safe access token

The first step for a successful integration is making a POST request to the token generation endpoint. This call should be made on your backend; you should not expose the underlying code or API key in the frontend of your platform:

curl --request POST \\
  --url <https://api.portcast.io/api/v2/org/token> \\          
  --header 'accept: application/json' \\
  --header 'Content-Type: application/json' \\
  --header 'x-api-key: <your-api-key>' \\
  --data '{
    "customer": "Test Customer"
  }'

• Note the <your-api-key> string above; this should be replaced with your Org’s API key.
• Also, note the "customer": "Test Customer" JSON entry in the body of the request; this is how you can identify your sub-customer. Make sure to replace "Test Customer" with the customer identifier of your choice. This will be used to assign API usage to that specific sub-customer on your usage dashboard report.

A successful response to this call will look similar to the following:

{
    "token": "eyJhbGciOiAIUzY1NiTsIm9yZ19pZCI6IjVlOGIyYjg3LTQ4ZTgtNTZjYi1iYzhhLTU1NmRkOWJkOWUzMCIsInR5cCI6IkpXVCJ9.eyJleHBpcnkiOiIyMDI1LTAzLTI2VDEzOjU4OjM2LjU1MTAyOCswMDowMCIsIm9yZ19pZCI6IjVlOGIyYjg3LTQ4ZTgtNTZjYi2iYzhhLTS1NmRkOWJkOWUzMCJ.5eCtmLuwja3QaQA7LdHrIGrwQKgP1cVtyZrQe4sTrUU"
}

This token is valid for 4 hours. After this period the token is revoked for security reasons.

Step 2: Generate the iframe

We can now use the "token" attribute returned by the successful response above to generate the iframe source URL. To do that, we can replace the <token-goes-here> portion of the URL below with the token’s content:

<https://app.portcast.io/embed/sailing_schedules?token=><token-goes-here>

Here is how that URL would be integrated on a basic html document: