Documentation

Link Group and Provider Attribute Endpoints

Written by Cirrus Product Documentation | Apr 4, 2022 10:10:13 PM

Link Groups are a way to segregate linked data for a person. For example you may have a Test and Prod Link Groups which are used to separate account linking performed in your different environments.

LIST linkGroups

uri /linkGroups
description List linkGroups accessible to API key
http operation GET
success response 200
error response 403 authentication/authorization error

Required Parameters

Name Description Format
None    

Optional Parameters

Name Description Format
orgId The organization id Numeric; Must be >= 0.

Sample Request

The following is a valid request.

curl --location --request GET "https://apps.cirrusidentity.com/console/api/v2/linkGroups"
 

 

Sample Response

Here is the response that would be returned from the sample request. 

{
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups?limit=10&offset=0&orgId=99",
"count": 3,
"items": [
{
"id": "99991",
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups/99991",
"type": "linkGroup",
"shortName": "Test",
"description": "Test environment linked accounts",
"organization": {
"id": "99"
}
},
{
"id": "99992",
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups/99992",
"type": "linkGroup",
"shortName": "Prod",
"description": "Production environment linked accounts",
"organization": {
"id": "99"
}
},
{
"id": "99993",
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups/99993",
"type": "linkGroup",
"shortName": "example",
"description": "Example environment linked accounts",
"organization": {
"id": "99"
}
}
]
}
 

 

LIST providerAttributes

uri /providerAttributes
description List the providerAttributes based on selection criteria.
http operation GET
success response 200
error response 403 authentication/authorization error

Required Parameters

Call the API with one of the following selection parameters: 

Name Description Format
linkGroupId A valid linkGroupId provide by the /linkGroups API Numeric; Must be >= 0
  Or  
guestId A valid guest id rfc4122 UUID Type 4
 
Or
 
linkGroupId A valid linkGroupId provide by the /linkGroups API Numeric; Must be >= 0
sorId Optional - A valid system-of-record identifier, often the entityId of a SAML identity provider. Alphanumeric; Optional
attributeName The attribute name to search on Alphanumeric
attributeValue The attribute value to search on Alphanumeric
ignoreValueCase Should case be ignored for the attribute value Boolean; "true" or "false"
 
Or
 
linkGroupId A valid linkGroupId provide by the /linkGroups API Numeric; Must be >= 0
sorId A valid system-of-record identifier, often the entityId of a SAML identity provider. Alphanumeric;
uid The identifier in the system-of-record Alphanumeric;

Optional Parameters

Name Description Format
offset The number of records to offset the page in the response. Numeric; Must be >= 0.
limit The number of records per page returned in the response. If a limit is not provided, a default limit of 500 per page will be returned. Numeric; Must be >= 0.

Sample Request

The following is a valid request that is selecting providerAttributes by linkGroupId, sorId, and uid.

curl --location --request GET "https://apps.cirrusidentity.com/console/api/v2/providerAttributes?linkGroupId=99999&sorId=https://my-system-of-record-entityid&uid=10100100010001001"
 

Sample Response

Here is the response that would be returned from the sample request. 

{
"href": "https://apps.cirrusidentity.com/console/api/v2/providerAttributes?limit=10&linkGroupId=99999&offset=0&sorId=https%3A%2F%2Fmy-system-of-record-entityid&uid=10100100010001001",
"count": 1,
"items": [
{
"id": "222222",
"href": "https://apps.cirrusidentity.com/console/api/v2/providerAttributes/222222",
"type": "providerAttributes",
"sorId": "https://my-system-of-record-entityid",
"uid": "10100100010001001",
"attributes": {
"urn:oid:0.9.2342.19200300.100.1.3": [
"homer@example.com"
],
"urn:oid:0.9.2342.19200300.100.1.1": [
"10100100010001001"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"eppn@example.com"
],
"urn:oid:2.5.4.42": [
"Homer"
],
"urn:oid:2.5.4.4": [
"Simpson"
]
},
"createDate": "2018-12-06T18:46:09Z",
"modifyDate": "2018-12-06T18:46:09Z",
"guest": {
"id": "aaaaaaaa-bbbb-4444-cccc-555555555555",
"href": "https://apps.cirrusidentity.com/console/api/v2/guest/aaaaaaaa-bbbb-4444-cccc-555555555555",
"type": "guest"
},
"linkGroup": {
"id": "99999",
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups/99999",
"type": "linkGroup",
"shortName": "Test"
}
}
]
}
 

Sample Request

The following is a valid request with pagination controls.

curl --location --request GET "https://apps.cirrusidentity.com/console/api/v2/providerAttributes?linkGroupId=99999&limit=4&offset=2"

Sample Response

Here is the response that would be returned from the sample request. 

Placeholder for future capture

 

REPLACE providerAttributes

uri /providerAttributes/{id}
description Overwrite the entire providerAttribute record referenced by id with a JSON object provided
http operation PUT
success response 200
error response 403 authentication/authorization error

Required Parameters

Name Description Format
id The numeric id of the providerAttribute record. Numeric; Must be >= 0
JSON Document The body of the PUT should be a JSON document with a content-type of "application/json" containing the following:  
sorId A valid system-of-record identifier, often the entityId of a SAML identity provider. Alphanumeric;
uid The identifier in the system-of-record Alphanumeric;
attributes A collection of attributeName-attributeValue pairs JSON formatted name:value pairs
guest A collection of the "id" attribute name and guest type 4 uuid values associated with the providerAttribute JSON formatted name:value pairs

Optional Parameters

Name Description Format
None    

Sample Request

The following is a valid request.

curl --location --request PUT "https://apps.cirrusidentity.com/console/api/v2/providerAttributes/22222" \
--header "Content-Type: application/json" \
--data "{
\"sorId\": \"https://google.cirrusidentity.com/gateway\",
\"uid\": \"101001000100001000001\",
\"attributes\": {
\"newAttribute\": \"newValue\",
\"multiAttribute\": [\"val1\",\"val2\"]
},
\"guest\": {
\"id\": \"aaaaaaaa-bbbb-4444-cccc-222222222222\"
}
}"
 

Sample Response

Here is the response that would be returned from the sample request. 

Placeholder for future capture

 

REPLACE all attributes inside of providerAttributes object

uri /providerAttributes/{id}/attributes
description If you want to only replace the attributes for a providerAttributes object and not send the rest of the object (as needed for regular updates). Calling with the PUT method will replace the entire attribute collection with what is provide by the JSON document (see POST method below to modify specific attributes).
http operation PUT
success response 200
error response 403 authentication/authorization error

Required Parameters

Name Description Format
id The numeric id of the providerAttribute record. Numeric; Must be >= 0
JSON Document The body of the PUT should be a JSON document with a content-type of "application/json" containing a collection of attributeName-attributeValue pairs JSON formatted name:value pairs

Optional Parameters

Name Description Format
None    

Sample Request

The following is a valid request.

curl --location --request PUT "https://apps.cirrusidentity.com/console/api/v2/providerAttributes/22222/attributes" \
--header "Content-Type: application/json" \
--data "{

\"anotherNewAttribute\": \"newValue\",
\"multiAttribute\": [\"val1\",\"val2\"]

}"
 

 

Sample Response

Here is the response that would be returned from the sample request. 

Placeholder for future capture

 

REPLACE or APPEND specific attributes inside of providerAttributes object

uri /providerAttributes/{id}/attributes
description If you want to replace or append specific attributes for a providerAttributes object. Calling with the PUT method will replace the entire attribute collection with what is provide by the JSON document (See PUT method above).
http operation POST
success response 200
error response 403 authentication/authorization error

Required Parameters

Name Description Format
id The numeric id of the providerAttribute record. Numeric; Must be >= 0
JSON Document The body of the PUT should be a JSON document with a content-type of "application/json" containing a collection of attributeName-attributeValue pairs JSON formatted name:value pairs

Optional Parameters

Name Description Format
None    

Sample Request

The following is a valid request:

curl -u $apiKey:$apiSecret \
> -X POST \
> -H 'Content-Type: application/json' \
> -d @update_pa_alice_ent_idp.json \
> "$apiBase/providerAttributes/278875/attributes"


JSON file "update_pa_alice_ent_idp.json"

{
"urn:oid:2.16.840.1.113730.3.1.241": [
"Alice Jane Arcus"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"employee@athena-institute.net"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.1": [
"employee"
]
}
 

Sample Response

Here is the response that would be returned from the sample request. 

{
"id": "278875",
"href": "https://apps.cirrusidentity.com/console/api/v2/providerAttributes/278875",
"type": "providerAttributes",
"sorId": "https://sso.athena-institute.net/idp",
"uid": "alice.arcus@athena-institute.net",
"attributes": {
"urn:oid:0.9.2342.19200300.100.1.1": [
"alice.arcus@athena-institute.net"
],
"urn:oid:2.5.4.42": [
"Alice"
],
"urn:oid:2.5.4.4": [
"Arcus"
],
"urn:oid:2.16.840.1.113730.3.1.241": [
"Alice Jane Arcus"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"alice.arcus@athena-institute.net"
],
"urn:oid:0.9.2342.19200300.100.1.3": [
"alice.arcus@athena-institute.net"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.1": [
"employee"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.9": [
"employee@athena-institute.net"
]
},
"createDate": "2019-01-03T19:00:58Z",
"modifyDate": "2019-01-03T21:34:36Z",
"guest": {
"id": "48680b15-8499-400a-8a81-e468b637f52d",
"href": "https://apps.cirrusidentity.com/console/api/v2/guest/48680b15-8499-400a-8a81-e468b637f52d",
"type": "guest"
},
"linkGroup": {
"id": "151648",
"href": "https://apps.cirrusidentity.com/console/api/v2/linkGroups/151648",
"type": "linkGroup",
"shortName": "Prod"
}
}
 

 

CREATE providerAttributes

uri /providerAttributes
description Create additional provider attributes for a guest. You'll need the system of record entityId and the optionally the attributes. The Cirrus account linking proxy will use the uid field for lookup and linking.
http operation POST
success response 201
error response 403 authentication/authorization error

Required Parameters

Name Description Format
JSON Document The body of the PUT should be a JSON document with a content-type of "application/json" containing the following:  
sorId A valid system-of-record identifier, often the entityId of a SAML identity provider. Alphanumeric;
uid The identifier in the system-of-record Alphanumeric;
guest A collection of the "id" attribute name and guest type 4 uuid values associated with the providerAttribute JSON formatted name:value pairs
attributes A collection of attributeName-attributeValue pairs JSON formatted name:value pairs

Optional Parameters

Name Description Format
None    

Sample Request

The following is a valid request:

curl --location --request POST "https://apps.cirrusidentity.com/console/api/v2/providerAttributes" \
--header "Content-Type: application/json" \
--data "{
\"sorId\": \"https://my-system-of-record-entityid\",
\"uid\": \"10100100010000100\",
\"guest\": {
\"id\": \"aaaaaaaa-bbbb-4444-cccc-222222222222\"
},
\"attributes\": {
\"urn:oid:0.9.2342.19200300.100.1.3\": [
\"homer@example.com\"
],
\"urn:oid:0.9.2342.19200300.100.1.1\": [
\"10100100010000100\"
],
\"urn:oid:1.3.6.1.4.1.5923.1.1.1.6\": [
\"eppn@example.com\"
],
\"urn:oid:2.5.4.42\": [
\"Homer\"
],
\"urn:oid:2.5.4.4\": [
\"Simpson\"
]
}
}"
 

Sample Response

Here is the response that would be returned from the sample request. 

{
"id": "222222",
"href": "https://apps.uat.cirrusidentity.com/console/api/v2/providerAttributes/222222",
"type": "providerAttributes",
"sorId": "https://my-system-of-record-entityid",
"uid": "10100100010000100",
"attributes": {
"urn:oid:0.9.2342.19200300.100.1.3": [
"homer@example.com"
],
"urn:oid:0.9.2342.19200300.100.1.1": [
"10100100010000100"
],
"urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [
"eppn@example.com"
],
"urn:oid:2.5.4.42": [
"Homer"
],
"urn:oid:2.5.4.4": [
"Simpson"
]
},
"createDate": "2018-12-06T18:46:09Z",
"modifyDate": "2018-12-06T18:46:09Z",
"guest": {
"id": "aaaaaaaa-bbbb-4444-cccc-222222222222",
"href": "https://apps.uat.cirrusidentity.com/console/api/v2/guest/aaaaaaaa-bbbb-4444-cccc-222222222222",
"type": "guest"
},
"linkGroup": {
"id": "99999",
"href": "https://apps.uat.cirrusidentity.com/console/api/v2/linkGroups/99999",
"type": "linkGroup",
"shortName": "Test"
}
}

 

DELETE providerAttributes

uri /providerAttributes/{id}
description Delete a providerAttribute record
http operation DELETE
success response 204
error response 403 authentication/authorization error
404 not found

Required Parameters

Name Description Format
id The numeric id of the providerAttribute record. Numeric; Must be >= 0

Optional Parameters

Name Description Format
None    

Sample Request

Placeholder for future capture