Getting Technical: API Keys for Administrators
Published December 15, 2024
Our Application Programming Interface, or API, provides a tool for directly communicating with your Sona site. Before we go any further, you should meet the following two requirements:
- You have the necessary technical knowledge
- You are an administrator
If you are a Sona administrator, but are unsure if using the Sona API is for you, then you can take a look at our API Documentation (this is accessible with the rest of the documentation you can access by selecting “Help and Documentation” from the Administrator dropdown menu on your Sona site).
If the API Documentation looks like it was written in at least two different languages (only one of them spoken by humans), then you may want to contact your IT department to write any code for you. On the other hand, if the documentation is more-or-less readable to you, then it’s something you’ll want to have anyway!
API Keys
Creating API Keys
Just in case you skipped down to this section in a rush to create your API key, it’s worth reiterating that only accounts with an administrator role can use the API. It’s also worth noting that not even adminstrators have an API key by default (even if it’s the default “Administrator” account that came with your Sona site!). API keys must be added to administrator accounts.
With those caveats out of the way, we can show you how to add an API key. First, select View and Edit Users from the User Management Dropdown menu and navigate to the desired user’s Update User Information page. Next, scroll down this page until you get to the section “API Key”:
This will take you to the API generation page for the user you selected. Click “Generate API Key” to generate a key for this user:
You should see a system message indicating success:
That’s it! The user now has an API key.
You may notice, after generating this key, that it is hidden by default for security reasons. If you would like to view the generated key, click on the “eye” icon (as shown below):
Disable a User’s API Key Access
We’ve just learned how to add an API Key to an administrator’s account. The next logical step is how to learn how to disable one! Luckily, this is quite simple. Most of the steps are the same as those just covered which you used to add a key.
First, go to the user’s Update User Information (just as described in the previous section). Scroll down to the API Key section and click on the Change API Key button:
This will take you to the same page that you used to create the API Key. Now, however, the options are a bit different:
In case it isn’t clear, the button you’ll want to disable a user’s API Key is the “Delete API Key” button.
And you’re done! Key disabled. Simple, just as we promised.
Out with the Old: No More Username/Password API Access
If Sona’s API is familiar to you, we still have important information that may not be. We are switching to API Key access only.
To give some context here, users could previously access the API using a username and password. For security reasons (as well as to improve SSO integration), this will no longer be true.
That’s one reason for this post. Not simply to inform you about this change (as important as that is), but to give you an easy guide to the new API authentication method. As you can tell, it’s simple, and it’s also more secure.
If you’ve never used the Sona API before, or never used the older authentication method before, then don’t worry!
We’ve now covered the important updates to our API, but stay tuned to for more possible updates in the feature!
