Skip to main content

SDK credentials

API host​

During installation of Atomic SDKs into your apps, you'll need to provide an API Host URL that's unique to your Atomic Organization. The Atomic SDK uses this to connect to the Atomic platform.

You can locate your API Host in the API Host tab of the configuration area.

Workbench view of SDK API Host
Find your SDK API Host from the API Host tab of the configuration area

SDK API keys​

During installation of Atomic SDKs into your apps, you'll also configure your apps to pass our SDK a JSON Web Token (JWT) signed by your app using a private key. This token verifies the identity and authentication of the current end user and our SDKs pass this to our platform with each and every request, so the platform can check each request is for a properly authenticated user and session. To complete the check the Atomic platform use the corresponding pubic key from your key-pair, which you need to have uploaded into the workbench.

In the workbench, the public key you upload is referred to as an SDK API Key.

Before continuing the below steps to add an API key, make sure you have created your key pair, and have read the SDK Authentication article.

Add an API Key​

Workbench view of SDK API keys
Find and manage SDK API keys from the API Keys tab of the configuration area
  1. From the Configuration section in the workbench sidebar menu, choose API Keys. Alternatively, open the command palette and type API Keys.
  2. Click New Key.
  3. Configure the settings
    • API key: the name for this key, this is the apiKey value provided to the SDKs.
    • max token expiry days (default: 7): the maximum number of days a JWT can be valid for.
    • type: "Client key" or "JWKS" (beta)
    • Public key / JWKS config: relevant configuration depending on chosen type.
    • Allowed JWT issuers (optional): a whitelist of allowed issuer values for the JWTs.
    • JWT Claim mappings: used to map values from a JWT to user profile, see below.
  4. select 'Add'
Workbench view of creating a new SDK API key
Add a new SDK API key

Mapping customer profile values from JWTs into Custom Profile fields​

Often JWTs contain customer profile data beyond a user id, for example a name, email, or other details. These data points can be extracted from JWTs automatically and stored in the corresponding customer profile in Atomic, by mapping the individual values from the JWTs to customer profile field names. This often involves creating custom profile fields for just this purpose, but values can also be mapped to the standard profile fields.

In the API key configuration, modify the JWT mapping JSON to configure which fields should be mapped into your custom profile records.

// Left is the name of a profile field, or custom profile field
// Right is the name of the item/claim in your JWT which holds the current value

{
  "aCustomFieldName" : "yourItemNameInJWT"
}
Workbench view of defining a JWT mapping while configuring an SDK API key
Create a mapping to save JWT values into custom profile values

Rotating API Keys​

To rotate your SDK API key perform the following:

  1. Add your new SDK API key to the Atomic Workbench, following the above guide to add an API key.
  2. Update your SDK to use the new key.
  3. Once you are confident that all of your users are using the updated key you can disable the old key in the Atomic Workbench from the overflow menu on the SDK API keys page.

Relates​

Last updated on