Authenticating to the SoftLayer API
Every call to the the SoftLayer API is authenticated using a SoftLayer customer portal account and a special API access key. Authenticating with a portal account ties your API call to your customer account and allows the API to enforce permission restrictions when processing your request.
The Authenticate Header
Every call to the SoftLayer API without exception must have an authentication header passed along with it. SoftLayer API authentication is modeled in the authenticate data type. Authenticate contains two strings,
username which contains your portal/API username, and apiKey which contains your API access key. If you don't provide the authenticate header the API returns the exception "No valid authentication headers found.", and if you provide an invalid username and apiKey combination the API returns the exception "Invalid API Token".
A SOAP representation of the authenticate header looks like this:
<authenticate xsi:type="slt:authenticate" xmlns:slt="http://api.service.softlayer.com/soap/v3/SLTypes/"> <username xsi:type="xsd:string">MY_USERNAME</username> <apiKey xsi:type="xsd:string">MY_API_ACCESS_KEY</apiKey> </authenticate>
while it's XML-RPC counterpart looks like this:
<struct> <member> <name>authenticate</name> <value> <struct> <member> <name>username</name> <value> <string>MY_USERNAME</string> </value> </member> <member> <name>apiKey</name> <value> <string>MY_API_ACCESS_KEY</string> </value> </member> </struct> </value> </member> </struct>
Generating Your API Key
There are two ways to generate an API access key, via the portal or by direct API calls. To generate your own API access key in the customer portal:
- Log into the SoftLayer customer portal with your customer account master user's username and portal password.
- Click the administrative then API Access links.
- Select the user you wish to generate a key for and click Generate API Access Key
To generate an API access key via API calls invoke the addApiAuthenticationKey method in the SoftLayer_User_Customer service. To remove a user's API access key execute the removeApiAuthenticationKey method in the same service. Be careful when removing API access keys. Removing these keys will remove that user's ability to use the SoftLayer API.