Skip to main content

Using the Optimove API

Natalie Samuels
  • Updated
Please Note:
 
Effective October 1st 2024, Optimove will no longer support the username and password method for the authentication of API calls. From this date on, the Optimove API will only support token-based authentication using API Keys. By this date, we request that you update your existing integrations to use API Keys to prevent login failures.
 
In this article, you will learn how to generate an API Key. You can also read the Optimove Developer Hub to learn how to implement your API Keys.
 
 

Generating API Keys

You can gain access to your Optimove data and trigger actions within Optimove via API. To enable an efficient and secure process, API requests are authenticated using API Keys. 
 
An API key is a code that is passed in by computer programs calling an API to identify the calling program and to provide access to the resources that the caller is authorized to use. The key acts as a secret code that is used to identify the user, application, or developer. It is also known as an API token.
 
API Keys ensure maximum security and only provide authorized applications access to the resources. By using API keys, we can easily revoke access to a specific application without impacting other applications.
 
Using an API Key does not require a preliminary request to the /login endpoint. By embedding the key in the request header, the user is “always logged in”. 
 

How to generate an API Key

  1. As an admin user, go to the Settings page
  2. Under General, go to API Key Management 
  3. Click the “+ New API Key” button

Untitled__21_.png

 
  1. Select a “Nickname” - an identifiable name easy to connect to the it’s actual user.
  2. Fill in your Contact Email 
  3. Select an Access Type:
    1. Select Admin for API full permitted user.
    2. Select 3rd party for channel integration purposes.
  4. Click on “Activate key”
  5. You will then be provided with a unique API key that will be used for authentication purposes.

Please note

API keys should be stored securely. We should never hard-code the API key in the application code or store it in plain text. It is recommended to use a secure key-value store like HashiCorp Vault or AWS Secrets Manager to store the API key.
 
Untitled__22_.png
 
For more information on using API Keys, refer to our Authentication Guide.  

 

Access Types

There are three options for Access Type: 

Admin

Admin users have unrestricted access to all API endpoints without functional limitations. 

 

3rd Party User

Third-party keys are limited in access permissions. Only a part of the API calls are available, as listed here.

The "3rd Party" role is designed for users who require access to specific functionalities for general functions, action-related operations, target group-related operations, and external systems integration.

The permissions for this role are defined during the generation of the user token, therefore limiting to specific access permissions. 

  • Within the API calls available, only certain attributes can be limited to be shared with the 3rd Party provider.
  • Additionally, only specific channels can be enabled to a certain CID.
  • For both limitations, if none is selected all channels are permitted

 

Transactional API User 

The "Transactional" user role provides access to all endpoints, including the "transactional" functionality.

Users with this role can utilize the full range of API endpoints, including those related to transactional operations.

Please ensure that users are assigned the appropriate roles and permissions based on their intended usage and the level of access required.

 

Best Practices 

To ensure the security of your APIs and prevent unauthorized access to your resources, follow these best practices:

  • Use a different API key for each application.
  • Regenerate API keys periodically.
  • Never share API keys on public platforms like GitHub.
  • Use HTTPS to transmit API keys.
  • Set up rate limits to control the usage of API keys.
  • Monitor API key usage regularly.

Related articles