How to Set up API Keys

Important: Before starting you must be a user with the appropriate user roles to access the API Keys section within the InControl Portal. 

These Roles Include: 

• Advanced Admin 
• Admin + API 

To generate your API key, first ensure you're logged into the Mp InControl portal. Then follow these steps:

1. Navigate to the Settings drop-down in your menu bar.
2. Select the API Keys section from the options available under Settings.

Click on the '+ Add API Key' button to open the API Key form. 

To fill out the form you’ll need to choose the Application, Role, and Account that you want the key to apply to:

• Application: Choose your current application (this will usually be the first option in the drop-down list).
• Role: Select your current role to match your in-portal permissions.
• Account: This is typically auto-filled with the highest level available to you.

Optional (but recommended): Give your API key a unique name. This is particularly helpful if you plan to generate multiple keys or already have several, as it makes it easier to distinguish between them.

After selecting the parameters, click 'Submit' to generate your API Key. The key will come with associated information, including the Client ID and Client Secret.

Important: This information will only be displayed once, so it's crucial to save it somewhere secure and accessible.

Step 2: Authorize with API Key

Whichever API client you use, the only way to get authorized is to add a Header with value of your Client Id & Client Secret. 

If you chose Postman as your API client it's needed to create a Collection and add a Request. 

After the request is created, you need to reselect default method to POST (no matter which of CRUD actions you want to perform, in graphQL they are all executed by POST). 

Later you need to insert the URL Address of generated API Key Application with '/api' at the end. 

If you've selected your current Application, you can merely copy the InControl website URL Address before the first slash, e.g., https://example.inchargeus.net. 

If you have chosen another Application, you can look up the target endpoint in Application detail page (click needed link in Application column in the API Keys list). 

Now click Headers tab under URL Address field. Here type 'Authorization' into KEY input and type 'Bearer <ClientId>:<ClientSecret>' into VALUE input. 

Step 3: Send a Request

Now switch Body tab, click on GraphQl radio button. Two new fields will appear: Query and GraphQl Variables. 

Useful link for InCharger API Documentation Explorer.

Follow the link and get queries, mutations and subscriptions schemas by clicking on <Docs button in the right middle. 

Use search bar to find operation you are interested in. Required arguments have an exclamation mark '!' while optional don't. 

Below is an example of a request to get a list of chargers sorted by their Serial Number (descending) - find RootQueryType.chargers in InCharger API Documentation (link above). 

Query input:

and GraphQl Variable input:

Congrats! if you're seeing Status 200 and no errors, you're all good. We will discuss some possible mistakes below under the "What could have gone wrong?" paragraph. 

It's important to mention that not all operations are available with API Keys. As when using an API Key no user is technically created, therefore most user-dependent features will not work for you. The list of unsupported operations are as follows: 

• currentUser
• currentUserAuthorization 
• ping
• logout 
• updatePassword
• updateEmail 
• updateProfile 
• setUserPreferences 
• all notification rule queries/mutations
• all export mutations 
• all filter queries/mutations
• signTosVersion mutation 

If you got such error "code": "unauthenticated", this means you're most likely to have either invalid Client Id or invalid Client Secret or you're trying to connect to the wrong Application (check endpoint in URL Address - it must be Application that is set for your API Key). 

If you got "code": "access_denied" error, perhaps the roles of your API Key does not contain permissions one needs to execute the operation. 

"code": "not_found" means you're requesting a non existing entity id (perhaps deleted or not accessible for your Account scope)