For Developers

Handling API Secrets

Some entities have a secret associated with them. For example, your Edlink application has a secret that is used to authenticate with Edlink. This is your application_secret and is used to 'sign' Oauth requests to Edlink among other things. Integrations also each have a secret, called an access_token, that is used to authenticate with Edlink. This secret operates as a bearer token and is your primary means of authenticating with the API for that integration.

These keys will identify you in requests and are to be kept private. They are not to be used client-side and should be stored securely. Should you ever find the integrity of your secret is compromised, you can reach out to your contact at Edlink, submit a support ticket, or email us at accounts@ed.link to have it reset.

You should treat Edlink secrets like passwords. They should be stored and exchanged securely and never used client side. Do not store secrets in plain text; use a password manager or a key management system. If you are storing secrets in a database, make sure you use a secure connection and that the database is not publicly accessible.

Be careful not to log secrets to the console or any other log files. And never store secrets in version control. Don't bundle secrets with your application. If you are using a build system, ensure you do not include secrets in any built assets.

Keeping Secrets

One of the most important facets of keeping a secure connection with Edlink is ensuring that your secrets stay in your control.

There are many secrets that need to be kept private, and the consequences for losing any of them could be problematic, to say the least. Among the most important of these is a user's access_token and refresh_token. During the user authorization flow, these tokens allow you to act on behalf of a user in the Edlink API.

Another important secret is your application's Secret Key. This key can be found on your application's configuration page, and it allows us to verify your identity during the user authorization flow.

Finally, there's your Integration Access Tokens. These are the tokens you use to make Graph API requests, and are found on your integration summary page.

To ensure best security practices, we encourage the following:

  1. Never pass these keys to the client-side of your application. This means, in short, that you should only ever handle secrets in the backend (server-side), and you should never send secrets to any code that runs on an end-user's computer. This is a MUST.
  2. Never hard-code a secret. Your code repository should never hold a secret key. We recommend using tools like Keybase that are end-to-end encrypted, or physical media like USB flash drives that never leave your sight to transfer secrets.
  3. Want to go the extra mile? We recommend using a secret manager like Google Secret Manager to store your application's Secret Key. Using tools like these, you can ensure only authorized users and machines will have access. You can configure your application to programmatically retrieve the secret as necessary. You can quickly grant or revoke access when employees join or leave your organization.