Authentication for OData

All OData requests sent to the PlanningSpace API server require authentication based on a valid user account for the PlanningSpace tenant that is being queried. The server will first check that the OData request contains the right credentials for the user account, and then retrieve the requested data, in line with the tenant access permissions of the user account.

A user account can only access via the OData API the same tenant data that it is allowed to access via the PlanningSpace UI (i.e., as determined by the workgroup-based and individual account permissions).

HTTP Basic authentication

This type of authentication can be used with a 'Local' tenant user account, which is based on a username and password that are stored in the PlanningSpace tenant database.

In HTTP Basic Authentication the username and password must be sent as part of the header information of the OData HTTP request. This 'Authorization: Basic' header is not encrypted and so it will be readable by any process that can intercept the HTTP client-server communication. If the IPS Server has HTTPS (secure HTTP) enabled, then the entire HTTP request will be encrypted, which affords some protection to the user account credentials.

The value of the Authorization header is calculated as follows, assuming that 'PSUSER' and 'SECRET' are the values for the username and password.

1. Create the single string 'PSUSER:SECRET' (with a colon in-between, without spaces).
2. Convert the string to a byte array.
3. Encode the byte array using Base64 (for the example case the output will be 'UFNVU0VSOlNFQ1JFVA==')
4. Prepend the string 'Basic ' to get the final required string (for the example case: 'Basic UFNVU0VSOlNFQ1JFVA==')

Using an API Key with Basic authentication

If you do not have a 'Local' type PlanningSpace user account, or if you want to avoid using your explicit user credentials in API requests, then an alternative is to get an API Key for your user account. The process is explained in the PlanningSpace User Manual (Generate API Key).

The key is an alphanumeric string which looks similar to this:

API.D49F43E5C0E64E2481FE15CBFDF9BE72.4744D25EB5A13EAE1B31B39D82EF7781

You use the API key as the password for Basic authentication, with the string 'FeedKey' as the username. Thus the value for 'PSUSER:SECRET' in your API requests will be like this:

FeedKey:API.D49F43F1C0E64E2481FE15CBFDF9BE72.4744D25EB5A13EAE1B31B39D82EF7781

The allowed usernames are 'FeedKey' and 'Account Key'. These are the default values for the IPS server setting 'AllowedApiKeyNames' which can be changed by the IPS Administrator.

The API key is not stored in the PlanningSpace tenant, for reasons of security. If you lose the information you will need to generate a replacement key. Each PlanningSpace user account can support one API key; when you generate a new key, the previous one will be replaced. The PlanningSpace Administrator has the ability to delete the API Key for any user account.

Code sample (PowerShell)

It is simple to use Windows PowerShell to do ad hoc API requests or to write scripts. The 'Invoke-RestMethod' command is available in all versions of PowerShell. (OData requests use GET methods, and GET is the default method so it isn't necessary to use the 'Method' parameter with Invoke-RestMethod.)

In the following, you will need to replace the values 'PSUSER' and 'SECRET' with an actual username and password (or API Key) for your PlanningSpace tenant. This creates an encoded string containing the username and password:

$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(("{0}:{1}" -f 'PSUSER', 'SECRET')))

You only need to do this once until the PowerShell is re-started.

Also, for convenience, set '$tenantUrl' to the URL of your PlanningSpace tenant:

$tenantUrl = 'https://ipsserver.mycompany.com/TENANTNAME'

Then, send each API request as follows, with an 'Authorization' header:

Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/data/v1/Currencies?$top=3') -Headers @{'Authorization' = "Basic $base64AuthInfo"}

Note that although the API response will originally be in JSON format, the Invoke-RestMethod command will convert the response to a PowerShell object which can be more easily manipulated using native PowerShell operations. Alternatively, you can work with the JSON-format response by appending a pipe to the end of the command:

Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/data/v1/Currencies?$top=3') -Headers @{'Authorization' = "Basic $base64AuthInfo"} | ConvertTo-JSON

Note: 'ConvertTo-JSON' does not by default convert back all levels of the JSON expression. Use the '-Depth' option if the sub-levels do not convert.

Note for PowerShell: Be careful with the use of double quotes as a string delimiter, especially when you are using $ to write OData queries. In double-quoted strings the $ character is always interpreted as the start of a PowerShell variable name. To mark a literal $ character you need to use the back tick character, for example "`$top=3".