Credentials and environments
Three credentials, two environments, one rule: never write them in code.
Your three credentials
They are UUIDs that you get from the Secure Exchanges portal: see Get your credentials from the portal. In code, they are called:
| Credential | Name in code |
|---|---|
| Licence serial number | serial |
| API user | apiUser |
| API password | apiPassword |
Warning
Your three credentials are as sensitive as a password. Anyone who has them can send, read and delete messages on your behalf, and the usage is billed to you.
- Never write them in code or commit them to a repository. A secret pushed once to a remote repository is compromised: regenerate it.
- Store them in a secret manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) or, failing that, in a protected file outside the web root, readable only by the service account.
- Be careful with environment variables: they show up in memory dumps and in most error reporters.
Get your credentials from the portal
Credentials are generated for a user who has an API licence. Two ways to get them:
- By an administrator, with the permission to manage users:
- In the Secure Exchanges portal, open Licensing & users > User management.
- On the row of the user who will use the API, click the Manage license icon, assign them an API licence, then save.
- A key icon then appears on their row: click it.
- By the user themselves, if they already have an API licence: My account > API credentials > Receive my keys.
Either way, Secure Exchanges sends the user's address a secure message containing the serial, the API user and the API password. The portal shows the password that opens this message.
Important
- 15 minutes, a single opening. The message expires 15 minutes after it is sent and can be opened only once: open it right away and store the credentials in your secret store. If it has expired, request new keys.
- New keys replace the old ones. Requesting keys immediately disables the previous ones of that licence, as well as the connectors already linked to the licence (Outlook, Gmail…): update every application that uses them.
Production and preview
Your preview and production credentials are different: a production serial does not work in preview, and vice versa. Always test in preview first.
In .NET, the preview environment needs three settings, applied before any call and only in your test configuration.
A single call selects the environment: it sets both the API address and the address of the service that sends the emails.
using SecureExchangesSDK;
Uri endpoint;
if (isPreview) // read from your test configuration, never hard-coded
{
endpoint = new Uri("https://preview.secure-exchanges.com/_api/0217/0217.asmx");
// Set before any call. Must never run in production.
SettingsHelper.CustomFileHandler = "https://preview.secure-exchanges.com/Handler/ReadFileTob64.ashx";
SettingsHelper.CustomSEMSEndpoint = "https://previewsems.secure-exchanges.com/SEMS_api.asmx";
}
else
{
endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");
}