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.

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

SDK API keys

SDK API keys are not the same as API keys and paths

The Atomic Workbench has two separate areas that both contain "API keys", and they are used for different things:

• Configuration > SDK > API keys (this page): the public keys / JWKS the client SDKs use to verify end-user JWTs. This is what you need when integrating a mobile or web SDK.
• Configuration > API > API keys: the OAuth2 Client ID and Client Secret used to authenticate server-to-server requests against Atomic's REST APIs. See API keys and paths.

If you are setting up an SDK, you want the SDK API keys described on this page.

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 uses the corresponding public 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. You manage these under Configuration > SDK > API keys.

Which value is the apiKey the SDK needs?

When you initialise an SDK you pass an apiKey value, for example AtomicSession.initialise('<environmentId>', '<apiKey>'). This apiKey is the Key name you set when you add the SDK API key, not the public key you paste in, and not any generated ID shown in the list of keys.

So if you name your key production-web, then production-web is the value you pass to the SDK as its apiKey.

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.

Find and manage SDK API keys from the API Keys tab of the configuration area

Using a Private Key

Storing a public key with atomic you can then use the private key on the application side to generate a JWT.

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
   • Key name: the name for this key. This is the value you pass to the SDKs as the apiKey, so choose something memorable such as production-web.
   • Max token expiry days (default: 7): the maximum number of days a JWT can be valid for.
   • Key type: choose "Client key".
   • Enter public key: paste in the public key from your key-pair. This is the key Atomic uses to verify JWTs; it is not the value you pass to the SDK.
   • Allowed JWT issuers (optional): a whitelist of allowed issuer values for the JWTs.
   • JWT claim mappings (optional): used to map values from a JWT to a customer profile, see below.
4. Select Add.

Add a new SDK API key

Using a JSON Web Key Set (JWKS)

To provide more flexibility, especially when supporting multiple keys, JWKS is supported. This is useful when you need to rotate a key, but support both old and new for a period.

API Key ID vs JWKS kid (key id)

The API Key Id references the SDK API Key name used when creating the API Key

The KID (or key id) is an attribute of the JWT token used to target the specific key inside the JWKS.

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.
   • Key name: the name for this key. This is the value you pass to the SDKs as the apiKey, so choose something memorable such as production-web.
   • Max token expiry days (default: 7): the maximum number of days a JWT can be valid for.
   • Key type: choose "JWKS".
   • JWKS config: a valid JWKS payload containing one or more key entries.
4. Select Add.

When generating JWT's it is important that you provide the Key ID in the signed token to target the correct key in the JWKS for validation. See the SDK guide on generating tokens

NOTE:

If you want to use a JWKS from a hosted URL please contact us.

Add a new JWKS 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"
}

Create a mapping to save JWT values into custom profile values

Rotating API Keys

To rotate your SDK API key perform the following:

Using an API Key with Client Key type

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.

Using an API Key with JWKS

1. Update the SDK API key with the new JWKS. It should include the the old and new keys.

• Alternatively, add a new SDK API key and follow the instructions above for the Client Key

2. Once you are confident that all of your users are using the updated key you could remove the old key from the JWKS.

Relates

• SDK installation
• SDK authentication
• Creating custom profile fields