API Keys
Less than to read
The Sage Network API supports modern authentication strategies including JWT Bearer Tokens and API keys. The JWT Bearer Token process is intended for use with interactive processes that redirect the user to a Sage Network provided OAuth page, and the API key process is intended for use with unattended processes that make API calls without presenting a user interface to the end customer.
Token Expirations
Modern security requires the ability to revoke access to a token when it is exposed or otherwise rendered insecure. The following chart explains the expiration processes for these methods.
Some Sage Network products may also permit interactive login with Single-Sign-On. These applications defer to Microsoft’s Azure B2C login system for the management of passwords, and each user’s password is never known by Sage employees.
| Authentication System | Expiration Date | Revocation Process |
|---|---|---|
| JWT Bearer Token | Varies, but generally within one hour of creation | Log out or allow the token to expire. |
| API Key | No expiration date | Use the Revoke API Key method |
| Interactive Login with email address and password or SSO | Determined by user’s SSO policy | Delete the user account record |
Obtaining an API Key
To create an API key, you must first obtain a short lived Bearer Token for a user within the account. Instructions for obtaining this bearer token are on the JWT Bearer Tokens page. The API Key you create will have the same privilege levels as the person who creates the API Key.
Once you have a bearer token, use the API documentation page for Create API Key to create a named API key. Your request to the POST /api/v1/ApiKeys will contain a JSON encoded body with a name parameter:
{ "name": "My First Api Key" }
The response from the API appears as follows:
{
"apiKeyId": "468178b7-e262-42ca-86e4-7a995d7e8085",
"groupKey": "84b1ebfe-bdf4-4590-92ee-c41f140f9c63",
"name": "My First Api Key",
"apiKey": "LSPK-**REDACTED**",
"created": "2021-12-07T18:09:44.7351182Z",
"createdUserId": "efd80aa6-7331-4aa2-9032-b87e6af44bf2"
}
An API key is generated once and can never be generated again for security reasons. You will only be able to see your API key once, in the response to your call to the Create API Key endpoint.
You must record the value in the apiKey parameter in a safe location. This API Key is generated and can never be retrieved again. If you lose this data, you must revoke the API key and create a new one to replace the lost key.
Querying for API Keys
You can use the Query API Keys endpoint to list the API keys you have defined. However, this endpoint will not retrieve your API Key; it will only tell you that the API key exists and has not been revoked.
If you forgot to write down your apiKey when you called Create API Key, you will have to create a new one!
Authenticating with an API Key
You can recognize an API Key by its prefix: LSPK-. To make an API call using API Key authentication, add the header X-Api-Key to your request as shown in this example:
curl -X 'GET' \
'https://api.sbx.lockstep.io/api/v1/Companies/query?name startswith A' \
-H 'accept: application/json' \
-H 'X-Api-Key: LSPK-**REDACTED**'
API Keys and Onboarding
When a new Sage Network application enrollment is created during onboarding, Sage Network creates a custom API Key for this app enrollment and delivers the API key for this application during its onboarding experience. This API Key is authorized for just that one group key and can only work with data for that one group.