The REST APIs used for establishing and removing federated friendship follow the pattern documented in Using the Controller APIs. This page lists and describes the APIs. For an overview of configuration federated friendships, see Configure Federated Friendship.
Create API Key for Federation
Creates an API key for an account. A second account (friend account) must use the API key to establish a level of trust called federated friendship between itself and the account.
|apikeyName||Arbitrary name for the API key. If you post an empty JSON object, the Controller automatically assigns a name for the API key.||No|
|id||Unique ID for the API key.|
|accountId||The account to which the API key belongs.|
|name||Name for the key.|
|description||Human readable description of the key.|
|key||The key itself. Required to establish federated friendship.|
|expiryDate||Date the key expires, if any. A value of -1 means the key does not expire. Will always show -1 by default.|
|canExpire||Indicates whether the key can expire. Will always show "false" by default.|
|state||Indicates whether the key is valid to make federation requests with. The state of the key can be "enabled", "disabled", etc. Will always show "enabled" by default.|
Federation specific API keys that are generated through federation REST endpoints will always generate API keys that do not expire. You currently cannot specify expiration date for federation specific API keys through federation REST endpoints. The expiryDate, canExpire, and state properties can be modified later by the Controller/Account admin.
Establish Mutual Friendship
Provides the Controller with data it needs to establish federated friendship between two accounts. Create an API key for federation on the current account.
|accountName||Name of the account where you are posting the API. If empty, assumes the currently logged in user.||NO|
|controllerUrl||Controller URL for the account. If empty assumes the default Controller URL for the account. The friend account must be able to access the account at this URL. If you have enabled SSL, the certificate must be valid and trusted for this URL.||NO|
|friendAccountName||The name of the friend account with which you are establishing trust.||YES|
|friendAccountApiKey||API key for the friend account with which you are establishing trust. The value of "key" from the apikeyforfederation API.||YES|
|friendAccountControllerUrl||Controller URL where the current account can access the friend account. If you have enabled SSL, the certificate must be valid and trusted for this URL.||YES|
Returns standard HTTP codes. 200 indicates the call executed successfully.
Retrieve API Key for Federation
(New in 4.4.3) Gets the API keys for friendship accounts. The API keys can then be used to remove mutual friendships.
|id||Unique ID for the API key.|
|version||Version of the federated friendship.|
|configKey||The friendship configuration key.|
|friendAccountKey||Account key for the friend account with which you have established trust.|
|friendApiKey||API key for the friend account with which you have established trust.|
|friendControllerHost||Controller host for the friend account with which you have established trust.|
|friendControllerPort||Controller port for the friend account with which you have established trust.|
|friendControllerProtocol||Controller protocol for the friend account with which you have established trust.|
|accountKey||Account key for the current account.|
|lastUpdateTimestamp||The last time the friendship was updated.|
|markedForDeletion||Indicates whether the friendship is scheduled for deletion.|
Remove Mutual Friendship
(New in 4.4.3) Provides the Controller with data it needs to remove federated friendship between two accounts. You can use the mutual unfriend API to complete your request. It requires account keys for both the local and friend Controller accounts.
Returns standard HTTP codes. 204 indicates the call executed successfully. 404 indicates the friendship pair is invalid.