Generate API Key

Note: Access to the 'Generate API key' function and using an API key to access the Planning Space APIs requires a user account to be granted the role 'Security/API Key' (see Roles).

The API Key is a string token that you can use to access your Planning Space data using a Web API or OData connection. Its intended uses are for OData (also known as Integration Services) access, or for when the Web API is used for automation purposes. For more information, see the Planning Space Web API Documentation.

If your Planning Space user account is externally-authenticated (i.e., it is a SAML2-type user account, usually having the form 'firstname.lastname@domain.mycompany.com') then you cannot authenticate directly to access the API; this includes when using an external analysis tool such as Excel or Power BI. You should use an API Key for OData API access, as explained below.

Note: An alternative 'Windows authentication' mode for OData API requests is available as an option, for SAML2-type user accounts. It is disabled by default and can be enabled by an IPS Administrator with the IPS service setting 'Enable Windows Authentication'. The setting applies to all Planning Space tenants and it is not possible to enable/disable at the tenant level.

Connect to the Planning Space tenant website

In a web browser, connect to the 'tenant web home' (which will have a URL of the form 'https://SERVERADDRESS/TENANTNAME'). Enter your user credentials to login. (See Launch Planning Space Web for more details.)

You need to login as the user that needs to be assigned an API key. This user account must already be granted the role 'Security/API Key' before the login; please check with your local Planning Space Administrator.

At the top right, click the dropdown menu which is labelled by your user identity. Click the menu item Generate API key.

You should see the Generate API Key page.

URL for direct access

You can connect directly to the page with the URL:

https://SERVERADDRESS/TENANTNAME/PlanningSpace/#/generateApiKey

with your own values for 'SERVERADDRESS' and 'TENANTNAME' inserted.

Generate an API key

Click the Create key button to generate a new key.

Click the Copy button next to the key field and immediately save the key in a safe location.

The key value is not stored in the Planning Space tenant, for reasons of security. If you lose the information you will need to generate a replacement key by re-visiting this web page.

Each Planning Space user account can support one API key. When you generate a new key, the previous one will be replaced. The Planning Space Administrator has the ability to delete the API Key for any user account.

API key expiry

API keys can be set to expire after a specific number of days, based on the IPS Service setting 'API Key Lifetime'. This requires IPS Administrator access to modify, and the same setting applies across all tenants.

The default setting is that expiry is disabled and API keys will have unlimited validity. Otherwise, a number of days can be set between 0 and 366 days; fractional days may be specified. Changing the setting does not affect the expiry date (or unlimited status) of existing API keys. The new setting will apply to API keys that are generated after the change has been made.

The expiry date-time for a new key is shown in the Generate API Key web page, when the key is generated, and it can also be checked later by re-visiting the page. The value 'INFINITE' is displayed when the API key has no expiry date.

Note: the stored key information for a user account does not change after the expiry date, therefore to determine if a user account has an active API key requires a comparison of the expiry date-time with the current date-time.

Using an API key in an OData client

You can use an API key in a data analysis application where you would otherwise use a Planning Space Username and Password to connect via OData.

For example, in Excel 2016 Power Query you would set up a new OData Feed, and at the authentication step, you select the Basic option, and use 'FeedKey' as the User name and the API key as the Password:

The allowed user names for Basic authentication are 'FeedKey' and 'Account Key'. These are set by the default value for the IPS server setting 'AllowedApiKeyNames', which can be changed by the IPS Administrator.