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

View full post