OrgBrandedID Endpoints

Overview

There is a separate set of the APIs used to access information for underlying account credentials stored in the Cirrus OrgBrandedID. The endpoints currently available are as follows:

  • Account Endpoints
    • List /{domain}/accounts
    • Get /{domain}/account
    • Create /{domain}/account
    • Update /{domain}/account/{cuid}
    • Reset /{domain}/account/{cuid}/reset
    • Suspend /{domain}/account/{cuid}/suspend
    • Reactivate /{domain}/account/{cuid}/reactivate

Base URI, Authorization, Responses, and Requests

The APIs for Cirrus OrgBrandedID use a base URI different from the invitation or account linking APIs. The base URI is:   

https://apps.cirrusidentity.com/cirrusid/api/v2

Authorization, responses and requests are handled the same as other V2 Cirrus APIs. See Overview- API v2 Basics for details.

LIST Accounts

uri /{domain}/accounts
description Paginated listing of all OrgBrandedID accounts for an organization's domain.
http operation GET
success response 200
error response 403 authentication/authorization error associated with the requested domain

 

Required Parameters

Name Description Format
domain Organization domain for the OrgBrandedID tenant rfc1035

 

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 which contains pagination parameters.

curl -u "$apiKey:$apiPswd" "$apiPath/athena-institute.net/accounts?limit=3"
 

Sample Response

Here is the response that would be returned from the sample request. Note: For brevity, some of the guest records have been replaced by ellipsis.

{

"count": 3623,
"accounts": [
{
"cuid": "cuid-edd04d83-8cb4-4387-81e2-fd02e0325389",
"username": "steve.cirrus.stratus+nqveyu@gmail.com",
"orgUserId": "steve.cirrus.stratus+nqveyu@gmail.com",
"selfRegSpId": null,
"createdAt": "2018-10-03T00:09:02Z",
"modifiedAt": "2018-10-03T00:09:07Z",
"statusDate": "2018-10-03T00:09:07Z",
"status": "ACTIVE",
"givenName": "Steve",
"middleName": null,
"surname": "Stratus 1538525341921",
"preferredName": null,
"email": "steve.cirrus.stratus+nqveyu@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": "",
"affiliations": null,
"customData": {}
},
{
"cuid": "cuid-be047014-f250-49ee-9507-dc42a4a079ef",
"username": "steve.cirrus.stratus+kisq97@gmail.com",
"orgUserId": "steve.cirrus.stratus+kisq97@gmail.com",
"selfRegSpId": null,
"createdAt": "2018-08-18T00:04:24Z",
"modifiedAt": "2018-08-18T00:04:29Z",
"statusDate": "2018-08-18T00:04:29Z",
"status": "ACTIVE",
"givenName": "Steve",
"middleName": null,
"surname": "Stratus 1534550662917",
"preferredName": null,
"email": "steve.cirrus.stratus+kisq97@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": "",
"affiliations": null,
"customData": {}


},

{

"cuid": "cuid-be047014-f250-49ee-9507-dc42a4a079ef",
"username": "steve.cirrus.stratus+kisq97@gmail.com",
"orgUserId": "steve.cirrus.stratus+kisq97@gmail.com",
"selfRegSpId": null,
"createdAt": "2018-08-18T00:04:24Z",
"modifiedAt": "2018-08-18T00:04:29Z",
"statusDate": "2018-08-18T00:04:29Z",
"status": "ACTIVE",
"givenName": "Steve",
"middleName": null,
"surname": "Stratus 1534550662917",
"preferredName": null,
"email": "steve.cirrus.stratus+kisq97@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": "",
"affiliations": null,
"customData": {}

},
...
]
}

Here is the response that would be returned from a request where the domain was not found or authorized by the API key. 

{

"error": {
"message": "Domain [example.net] not found."
}

}

GET Account

uri /{domain}/account?[email|cuid]={value}
description Return the attributes for an account.
http operation GET
success response 200
error response 403 authentication/authorization error
404 CUID not found

 

Required Parameters

Name Description Format
domain Organization domain for the OrgBrandedID tenant  rfc1035
Either "email" or "cuid" There is a choice of looking up the account by either the email address used to register (which must be unique), or the generated internal ID (cuid).  String
value The string value to perform the lookup String

 

Optional Parameters

None

 

Sample Request

The following is a valid request which contains all required and optional parameters.

curl -u "$apiKey:$apiPswd" "$apiPath/athena-institute.net/account?cuid=cuid-316bd03d-6494-4d37-88f7-9a1b2dabed75"
 

Sample Response

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

{

"cuid": "cuid-316bd03d-6494-4d37-88f7-9a1b2dabed75",
"username": "steve.cirrus.stratus+qdoqda@gmail.com",
"orgUserId": "steve.cirrus.stratus+qdoqda@gmail.com",
"selfRegSpId": null,
"createdAt": "2018-09-30T16:05:03Z",
"modifiedAt": "2018-09-30T16:05:08Z",
"statusDate": "2018-09-30T16:05:08Z",
"status": "ACTIVE",
"givenName": "Steve",
"middleName": null,
"surname": "Stratus 1538323502616",
"preferredName": null,
"email": "steve.cirrus.stratus+qdoqda@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": "",
"affiliations": null,
"customData": {}

}

Here is the response that would be returned from a request where the record is not found.

{

"error": {
"message": "Account for [cuid-316bd03d-6494-4d37-88f7-blah] not found."
}

}

Create Account

uri 
/{domain}/account
description Create a new OrgBrandedID account
http operation POST
success response 201
error response

400 other error -- most likely trying to create an account with an already registered email address

403 authentication/authorization error associated with the requested domain

422 unprocessable – invalid input JSON

 

Required Parameters

Name Description Format
domain Organization domain for the OrgBrandedID tenant  rfc1035
JSON document The body of the POST should be a JSON document with a content-type of "application/json" containing the information needed to create the account JSON Document

 

Optional Parameters

None

 

Sample JSON document

The following is an example of a JSON document to create an account:

{

"username" : "connie.contrail+20220707b@gmail.com",
"email" : "connie.contrail+20220707b@gmail.com",
"givenName" : "Connie - 20220707b",
"surname" : "Contrail",
"yearOfBirth" : "",
"phone" : "",
"returnUrl" : "",
"selfRegSpId" : "",
"orgUserId" : "connie.contrail+20220707b@gmail.com",
"affiliations": "",
"customData" : {"keyA": "valueA", "keyB": "valueB"}

}

 

Sample Request

The following is a valid request to create an account using the JSON document in the file "create_base_user.json"

curl -u $apiKey:$apiPswd -X POST -H 'Content-Type: application/json' -d @create_base_user.json "$apiPath/athena-institute.net/account/"
 

Sample Response

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

{

"cuid": "cuid-fc794872-7b9d-4ff2-a496-f6849c2939a0",
"username": "connie.contrail+20220707b@gmail.com",
"orgUserId": "connie.contrail+20220707b@gmail.com",
"selfRegSpId": null,
"createdAt": "2022-07-07T16:48:39Z",
"modifiedAt": "2022-07-07T16:48:39Z",
"statusDate": "2022-07-07T16:48:39Z",
"status": "BOOTSTRAP",
"givenName": "Connie - 20220707b",
"middleName": null,
"surname": "Contrail",
"preferredName": null,
"email": "connie.contrail+20220707b@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": null,
"affiliations": null,
"customData": {
"keyA": "valueA",
"keyB": "valueB"
}

}

Here is the response that would be returned if attempting to register the same email.

{"error":{"message":"Account for [connie.contrail+20220707b@gmail.com] exists and cannot be created again."}}

 

Update Account

uri 
/{domain}/account/{cuid}
description Update an OrgBrandedID account
http operation PUT
success response 200
error response

403 authentication/authorization error associated with the requested domain

404 account not found

422 unprocessable – invalid input JSON

 

Required Parameters

Name Description Format
domain Organization domain for the OrgBrandedID tenant  rfc1035
cuid The cuid associated with the OrgBrandedID account String
JSON document The body of the POST should be a JSON document with a content-type of "application/json" containing the information needed to create the account JSON Document

 

Optional Parameters

None

 

Sample JSON document

The following is an example of a JSON document to create an account:

{

"username" : "connie.contrail+20220707b@gmail.com",
"email" : "connie.contrail+20220707b@gmail.com",
"givenName" : "Connie - Changed",
"surname" : "Contrail - Changed",
"yearOfBirth" : "",
"phone" : "",
"returnUrl" : "",
"selfRegSpId" : "",
"orgUserId" : "connie.contrail+20220707b@gmail.com",
"affiliations": ["affilA","affilB"],
"customData" : {"keyA": "valueA"}

}

 

Sample Request

The following is a valid request to create an account using the JSON document in the file "change_base_user.json"

curl -u $apiKey:$apiPswd -X PUT -H 'Content-Type: application/json' -d @change_base_user.json "$apiPath/athena-institute.net/account/cuid-fc794872-7b9d-4ff2-a496-f6849c2939a0"
 

Sample Response

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

{

"cuid": "cuid-fc794872-7b9d-4ff2-a496-f6849c2939a0",
"username": "connie.contrail+20220707b@gmail.com",
"orgUserId": "connie.contrail+20220707b@gmail.com",
"selfRegSpId": null,
"createdAt": "2022-07-07T16:48:39Z",
"modifiedAt": "2022-07-07T18:11:45Z",
"statusDate": "2022-07-07T16:48:39Z",
"status": "BOOTSTRAP",
"givenName": "Connie - Changed",
"middleName": null,
"surname": "Contrail - Changed",
"preferredName": null,
"email": "connie.contrail+20220707b@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": null,
"affiliations": "affilA,affilB",
"customData": {
"keyA": "valueA"
}

}

Here is the response that would be returned if the account isn't found.

{"error":{"message":"Account for [cuid-fc794872-7b9d-4ff2-a496-blah] not found."}}

Reset Account

uri 
/{domain}/account/{cuid}/reset
description Reset the account by resending an activation
http operation POST
success response 200
error response

403 authentication/authorization error associated with the requested domain

404 cuid not found

 

Required Parameters

Name Description Format
domain Organization domain for the OrgBrandedID tenant  rfc1035
cuid The cuid associated with the OrgBrandedID account String

 

Optional Parameters

None

 

Sample Request

The following is a valid request to reset an account.

curl -u $apiKey:$apiPswd -X POST "$apiPath/athena-institute.net/account/cuid-edd04d83-8cb4-4387-81e2-fd02e0325389/reset"
 

Sample Response

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

{

"cuid": "cuid-edd04d83-8cb4-4387-81e2-fd02e0325389",
"username": "steve.cirrus.stratus+nqveyu@gmail.com",
"orgUserId": "steve.cirrus.stratus+nqveyu@gmail.com",
"selfRegSpId": null,
"createdAt": "2018-10-03T00:09:02Z",
"modifiedAt": "2022-07-07T18:26:05Z",
"statusDate": "2022-07-07T18:26:05Z",
"status": "BOOTSTRAP",
"givenName": "Steve",
"middleName": null,
"surname": "Stratus 1538525341921",
"preferredName": null,
"email": "steve.cirrus.stratus+nqveyu@gmail.com",
"phone": null,
"yearOfBirth": null,
"returnUrl": "",
"affiliations": null,
"customData": {}

}

Here is the response that would be returned if attempting to register the same email.

{"error":{"message":"Account for [cuid-edd04d83-8cb4-4387-81e2-blah] not found."}}

Suspend Account

uri

/{domain}/account/{cuid}/suspend

description

Suspend an account

http operation

POST

success response

200

error response

403 authentication/authorization error associated with the requested domain

404 cuid not found

 
 

Required Parameters

Name

Description

Format

domain

Organization domain for the OrgBrandedID tenant

rfc1035

cuid

The cuid associated with the OrgBrandedID account

String

 
 

Optional Parameters

None

 

Sample Request

The following is a valid request to suspend an account.

curl -u $apiKey:$apiPswd -X POST "$apiPath/athena-institute.net/account/cuid-edd04d83-8cb4-4387-81e2-fd02e0325389/suspend"

 

Sample Response

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

{

"cuid": "cuid-edd04d83-8cb4-4387-81e2-fd02e0325389",

"username": "steve.cirrus.stratus+nqveyu@gmail.com",

"orgUserId": "steve.cirrus.stratus+nqveyu@gmail.com",

"selfRegSpId": null,

"createdAt": "2018-10-03T00:09:02Z",

"modifiedAt": "2024-07-07T18:26:05Z",

"statusDate": "2024-07-07T18:26:05Z",

"status": "SUSPENDED",

"givenName": "Steve",

"middleName": null,

"surname": "Stratus 1538525341921",

"preferredName": null,

"email": "steve.cirrus.stratus+nqveyu@gmail.com",

"phone": null,

"yearOfBirth": null,

"returnUrl": "",

"affiliations": null,

"customData": {}

}

Here is the response that would be returned if attempting to register the same email.

{"error":{"message":"Account for [cuid-edd04d83-8cb4-4387-81e2-blah] not found."}}

 

Reactivate Account

uri

/{domain}/account/{cuid}/reactivate

description

Reactivate an account that was previously suspended by the suspend operation

http operation

POST

success response

200

error response

403 authentication/authorization error associated with the requested domain

404 cuid not found

 
 

Required Parameters

Name

Description

Format

domain

Organization domain for the OrgBrandedID tenant

rfc1035

cuid

The cuid associated with the OrgBrandedID account

String

 
 

Optional Parameters

None

 

Sample Request

The following is a valid request to reactivate an account.

curl -u $apiKey:$apiPswd -X POST "$apiPath/athena-institute.net/account/cuid-edd04d83-8cb4-4387-81e2-fd02e0325389/reactivate"

 

Sample Response

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

{

"cuid": "cuid-edd04d83-8cb4-4387-81e2-fd02e0325389",

"username": "steve.cirrus.stratus+nqveyu@gmail.com",

"orgUserId": "steve.cirrus.stratus+nqveyu@gmail.com",

"selfRegSpId": null,

"createdAt": "2018-10-03T00:09:02Z",

"modifiedAt": "2024-07-14T18:26:05Z",

"statusDate": "2024-07-14T18:26:05Z",

"status": "ACTIVE",

"givenName": "Steve",

"middleName": null,

"surname": "Stratus 1538525341921",

"preferredName": null,

"email": "steve.cirrus.stratus+nqveyu@gmail.com",

"phone": null,

"yearOfBirth": null,

"returnUrl": "",

"affiliations": null,

"customData": {}

}

 

Here is the response that would be returned if attempting to register the same email.

{"error":{"message":"Account for [cuid-edd04d83-8cb4-4387-81e2-blah] not found."}}

© Copyright Cirrus Identity, Inc.

 

Blog comments