API Tokens

An API Token lets a program sign in to the Magic Suite REST API. Magic Suite's own services use them to talk to each other. Tenant Admins can also create them for the users in their Tenant, and every user can create their own, to use the API directly: for example from C# with the MagicSuite.Api NuGet package, or from a tool such as Postman.

Where to manage API Tokens

  • Tenant Admins can create and manage the API Tokens of everyone in their Tenant in the Admin app, on the Users tab under API Tokens
  • Every user can view and manage their own API Tokens: click the Profile icon in any Magic Suite app, then the arrow beside My API Tokens

Enabled and Expires UTC

An API Token can be disabled, and can be given an expiry date and time in UTC. A disabled token, or one whose expiry has passed, can no longer be used to sign in: Magic Suite refuses requests made with it, just as it refuses a wrong key. Neither deletes the token, so ticking Enabled again, or moving the expiry into the future, brings it back into use with the same name and key.

  • A new token is set to expire a year after it is created. Clear Expires UTC on the form for a token that never expires
  • An expiry must be in the future when it is set or changed
  • The Expires UTC column shows an icon: green, then yellow within 31 days of the expiry, amber within 7 days, and red once it has passed
  • The Enabled column can be sorted and filtered, so disabled tokens are easy to find

Regenerating a key

To replace a token's secret key

  1. From your Profile, click the arrow next to API Keys.
  2. Select the required token and click the Regenerate Key button.
    You are asked to confirm first, because anything using the current key stops working straight away. 
  3. Because it is shown only once, click Copy to copy the new key straight away. It cannot be retrieved later.
  4. Update everything that uses this key and check everything relying on the key still works.
  5. Close the dialog box

Older API tokens are being retired

Some older API tokens use a security scheme that Magic Suite is retiring. If you own one, or are an administrator of a Tenant that has one, you receive an email naming the tokens affected and the date they will stop working, followed by reminders a week and a day before that date.

To keep a token working, use it once before the date in the email. It is upgraded to the current scheme automatically, and nothing else changes: the same name and key keep working.

If you would rather not wait for the token to be used, regenerate its key, or create a replacement token. Either way the token uses the current scheme straight away, but anything that uses it must be given the new key.

Note: the email identifies each token by the first few characters of its name, its description and when it was created. It never contains a token's key.

What happens on the date

A token from the email that has still not been used stops working, and Magic Suite refuses requests made with it. To restore access, create a replacement token and give its key to whatever used the old one.

Who should own an integration's tokens

Create the tokens for a system integration under an API-only user, not under a person. An API-only user has no email address and cannot sign in, so the integration does not depend on anyone's account, and no one is sent notices about its tokens. Tenant Admins create API-only users on the Users page, and then choose one as the Owner when creating a token.

If an integration's tokens are already assigned to a person, create an API-only user, create replacement tokens under it, point the integration at them and check that it still works, then delete the old tokens. Do not regenerate a token in place before the integration has been switched over, because that stops the integration working.

Notices about tokens that are about to stop working are sent to the token's owner when the owner has an email address, and always to the Tenant Admins of the owner's Tenant. For a token owned by an API-only user, the Tenant Admins receive the notice.

Reconnection

Reconnection

Reconnection

timed out

timed out

Attempt of

Reload
An unhandled error has occurred. Reload 🗙