PDFs

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.

Format

POST /controller/rest/federation/apikeyforfederation

POST Data

{
"apiKeyName":"<key name>"
}
PropertyValue DescriptionRequired
apikeyNameArbitrary name for the API key. If you post an empty JSON object, the Controller automatically assigns a name for the API key.No

Response Format

{
"id": string,
"accountId": int,
"name": string,
"description": string,
"key": string,
"expiryDate": int,
"canExpire": bool,
"state": string
}
PropertyValue description
idUnique ID for the API key.
accountIdThe account to which the API key belongs.
nameName for the key.
descriptionHuman readable description of the key.
keyThe key itself. Required to establish federated friendship.
expiryDateDate the key expires, if any. A value of -1 means the key does not expire. Will always show -1 by default.
canExpireIndicates whether the key can expire. Will always show "false" by default.
stateIndicates 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.

Format

POST /controller/rest/federation/establishmutualfriendship

POST Data

{
"accountName": string,
"controllerUrl": string,
"friendAccountName": string,
"friendAccountApiKey": string,
"friendAccountControllerUrl": string
}
PropertyValue DescriptionRequired
accountNameName of the account where you are posting the API. If empty, assumes the currently logged in user.NO
controllerUrlController 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
friendAccountNameThe name of the friend account with which you are establishing trust.YES
friendAccountApiKeyAPI key for the friend account with which you are establishing trust. The value of "key" from the apikeyforfederation API.YES
friendAccountControllerUrlController 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

Response Format

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.

Format

GET /controller/rest/federation/showFriends/account/<AccountKey>

Response Format

{
"id": string,
"version": string,
"configKey": string,
"friendAccountKey": string,
"friendApiKey": string,
"friendControllerHost": string,
"friendControllerPort": string,
"friendControllerProtocol": string,
"accountKey": string,
"lastUpdateTimestamp": int,
"markedForDeletion": bool
}
PropertyValue description
idUnique ID for the API key.
versionVersion of the federated friendship.
configKeyThe friendship configuration key.
friendAccountKeyAccount key for the friend account with which you have established trust.
friendApiKeyAPI key for the friend account with which you have established trust.
friendControllerHostController host for the friend account with which you have established trust.
friendControllerPortController port for the friend account with which you have established trust.
friendControllerProtocolController protocol for the friend account with which you have established trust.
accountKeyAccount key for the current account.
lastUpdateTimestampThe last time the friendship was updated.
markedForDeletionIndicates 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.

Format

DELETE /controller/rest/federation/mutualfriendship?accountKey={LocalAccount}&friendAccountKey={FriendAccount}

Response Format

Returns standard HTTP codes. 204 indicates the call executed successfully. 404 indicates the friendship pair is invalid.

  • No labels