You do not need a "Secret" API Key to access the Synap API. Instead, we have opted for a self-managed token approach using Personal Access Tokens.Personal Access Token (PAT)#
Requests to the Synap API must be authorised using a self-managed Personal Access Token (PAT). Any administrator account can generate one, or multiple PATs from the platform.In your Portal click "Settings", and under the "Automations" header, click "API". Here you can create a PAT. Just pick a name that will help you identify it, e.g. "dave-testing", or "Main Token". You'll be presented with the PAT in a green box. It should be a long string that looks like this p:<token>. Make sure you safely store this in your records as we will never display the token again.These tokens identify the request as pertaining to your organisation, and by default, are performed on behalf of the administrator who issued the token.Subject-User Requests#
Requests can be made on behalf of users other than those that issue PATs. To do so, in addition to your PAT token, you can provide the User ID of the Subject-User to act on their behalf.For example, if your use-case is to automatically set a profile picture on your students' accounts using an internal resource, you can send an update request to the User resource using your administrator issued PAT along with the newly registered student's User ID as the Subject-User. Such requests will for all intents-and-purposes be treated as though they were made by that "Subject User". Practically, this means that the Subject-User must themself have sufficient privileges to take the desired action. You cannot for example try to update your Portal's name whilst acting on behalf of an Educator; an Educator does not have sufficient privilges to modify your Portal's settings.PAT Security#
PATs are long-lived tokens without an explicit expiry, so treat them as highly sensitive. A leaked PAT could result in data breaches and data loss. You can revoke a PAT at any time, immediately rendering it unusable.Following a shared responsibility model, Synap will keep request logs (for a predefined period of time) in case requests must be audited for security purposes. If you suspect that your token has been leaked, or misused, please get in touch. Although Synap will look for suspicious activity, we cannot guarantee that no misuse has occured using your leaked tokens. Ultimately, you must follow strict protocols in your organisation to protect these tokens from threat actors. Modified at 2025-06-26 02:21:49
