The Lockstep platform 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 Lockstep-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 lockstep 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 Lockstep employees.

Authentication SystemExpiration DateRevocation Process
JWT Bearer TokenVaries, but generally within one hour of creationLog out or allow the token to expire.
API KeyNo expiration dateUse the Revoke API Key method
Interactive Login with email address and password or SSODetermined by user's SSO policyDelete 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"
}

🚧

Save your apiKey!

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 Lockstep application enrollment is created during onboarding, Lockstep 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.