Skip to main content

Advanced methods

The Pigeonhole Live API allows you to take advantage of additional functionalities that are not possible through the Dashboard.

Prerequisites
  • API Key (this will be assigned to the variable $API_KEY in this guide)
Objectives
  • Creating expiring links
  • Revoking expiring links

The Pigeonhole Live API allows you to create expiring links for accessing Sessions. Expiring links are disposable links you can create for every Session that will expire after a duration defined during its creation, also known as the Time to Live (ttl). Because expiring links are scoped to a Session, it allows you to have more fine grained control over access to your Pigeonhole. Currently, expiring links are only available for the Admin Panel.

For example, expiring links allows you to work with third parties to moderate Q&A Sessions, while also ensuring that they will not have access to other Sessions in the Pigeonhole. You can limit this further by setting a TTL, to close off access after the event ends.

To create an expiring link, you will need to have your Session ID. To fetch the list of Sessions in the Pigeonhole:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/sessions \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

This will return the list of Sessions in your Pigeonhole, take note of the Session ID:

{
  "data": [
    {
      "id": 31,
      "parentSessionId": 5,
      "name": "Session name",
      "description": "Example description",
      "location": "Example location",
      "startDate": "2022-08-25T05:22:05Z",
      "endDate": "2022-08-25T05:22:05Z",
      "createdAt": "2022-08-25T05:22:05Z",
      "type": "qna"
    }
  ],
  "links": {
    "next": null
  },
  "meta": {
    "perPage": 30,
    "nextCursor": null,
    "hasMore": false
  }
}

Then, with the Session ID, we can generate an expiring link. An expiring link is valid for the duration (in seconds) set in the ttl field. For example, to create a link that will expire in an hour:

curl -X POST https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/sessions/$SESSION_ID/one-time-links/generate \
  -d '{"for": "admin-panel", "ttl": 3600 }' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

You will get a response containing a token, link and the timestamp of its expiry:

{
  "data": {
    "for": "admin-panel",
    "token": "CTv5sJcF4vo9G32MUUqvrQaF2NCB8nJyaJn4KxqZnfQ4p7ZyisqjEvvP6Tk",
    "expiresAt": "2022-08-25T05:22:05Z",
    "expiresAtUnix": "1599626628",
    "used": false,
    "link": "https://api.pigeonhole.at/access/CTv5sJcF4vo9G32MUUqvrQaF2NCB8nJyaJn4KxqZnfQ4p7ZyisqjEvvP6Tk/a"
  }
}
Completed Objective

Creating expiring links

An expiring link can also be revoked at any time. If a user is using the link, they will be forced to log out. To revoke an expiring link, you need to have its token:

curl -X DELETE https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/sessions/$SESSION_ID/one-time-links/$TOKEN \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

If the token was revoked successfully, a response with status 204 will be returned.

Completed Objective

Revoking expiring links