Properly managing identifiers and secrets is crucial for maintaining the security and integrity of your integrations. Understanding the distinction between public IDs and private secrets, along with best practices for their handling, will protect your application and your users' data.
Edlink IDs are Public
Edlink uses UUIDs (v4 or occasionally, v5) to uniquely identify entities such as People, Classes, Schools, and Integrations. These IDs are considered public information. You can safely expose these IDs in URLs, client-side applications, or logs without compromising security. They are stable and designed for referencing and linking data across systems.
In general, we strongly encourage you to use these IDs in your application logic, as they provide a consistent way to reference entities across different Edlink API endpoints. For example, you can use a Person ID to fetch a user's profile or a Class ID to retrieve class details. Using these IDs is preferable to using other identifiers, such as email addresses or SIS ID, which may change over time, collide, or be less stable.
Secrets Must Remain Secret
In contrast, secrets such as Application Secret Keys, User Access Tokens, User Refresh Tokens, and Integration Access Tokens (Graph API tokens) must be kept strictly confidential. Never expose these secrets in client-side code, embed them in mobile applications, or commit them to version control. Secrets grant access to sensitive data and functionalities; their compromise can lead to unauthorized access and data breaches.
In particular, never make the OAuth 2.0 or OIDC token exchange process (which involves exchanging an Application Secret Key for an access token) directly from client-side code. Always perform this exchange on your secure backend server to prevent exposure of your secrets.
Best Practices for Handling Secrets
Treat all Edlink secrets with the same level of care you would afford passwords or private cryptographic keys.
- Server-Side Storage and Usage: All secrets should be stored and used exclusively on your secure backend servers. Client applications should make requests to your backend, which then uses the necessary Edlink secrets to interact with our API.
- Secure Storage: Store secrets in secure, encrypted storage solutions like environment variables, dedicated secret management services (e.g., HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager), or encrypted configuration files with restricted access. Avoid storing secrets in plaintext in your codebase or database.
- Environment Variables: For development and deployment, use environment variables to inject secrets into your application. This prevents them from being hardcoded or accidentally committed.
- Access Control: Limit access to systems and configurations containing secrets to authorized personnel only. Implement strong access controls and audit trails for these systems.
- Separating Code Environments: Use different secrets for development, staging, and production environments. This prevents accidental exposure of production secrets during development or testing.
Types of Secrets in Edlink
- User Access and Refresh Tokens: User access tokens are short-lived (typically 1 hour) and are used to make API calls on behalf of a user. Refresh tokens are long-lived and used to obtain new access tokens. Both must be stored securely on your server. Never send the refresh token to the client.
- Application Secret Key: This key is used in the OAuth 2.0 and OIDC token exchange process to authenticate your application. It is critical to keep this secret confidential.
- Integration Access Tokens (Graph API Tokens): These tokens grant broad access to an institution's data via the Graph API. Handle them with extreme care, as they do not expire by default.
Token Rotation
In general, it's good practice to rotate your secrets periodically or in response to security incidents. Edlink allows you to rotate your application secret key without service disruption, and we encourage you to do so as part of your security hygiene. For other types of secrets (such as Graph API tokens), you will need to contact Edlink support to initiate a rotation.
What to Do If You Suspect a Breach
If you suspect any Edlink-related secret has been compromised or that a security breach has occurred, contact Edlink support immediately. Prompt reporting allows us to take swift action to mitigate potential damage.
Edlink will work with you to reset compromised secrets, investigate the breach, and implement additional security measures as needed. We take security very seriously and are committed to protecting your data and integrations.