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 can only use an API Key for OData API access; this includes using an external analysis tool such as Excel or Power BI.
For version 16.5 Update 7 and later: An additional 'Windows authentication' mode for OData API requests is available, 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 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.
Click the dropdown menu in the top menu bar which is labelled by your user identity. The menu button Generate new API key should be visible:
Click the menu button and you should see the Generate API Key page:
(Note: there is another access button in the 'PlanningSpace Web' user interface, in case that is enabled as visible for users.)
URL for direct access
If the access buttons are not visible for any reason: first login to the tenant website, and then you should be able to 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 the 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
For version 16.5 Update 7 and later: 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 (this provides backward-compatibility with earlier versions of Planning Space). 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 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 always 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.