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
    • Delete /{domain}/account/{cuid}
  •  

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": {}
},
...
]
}
 

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

Name Description Format
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

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

Name Description Format
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

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

Name Description Format
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 201
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

Name Description Format
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."}}

Delete Account

uri /{domain}/account/{cuid}
description Delete an account
http operation DELETE
success response 204
error response 403 authentication/authorization error
404 UID not found or delete not allowed

Required Parameters

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

Optional Parameters

Name Description Format
None    

Sample Request

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

curl -i -u $apiKey:$apiPswd -X DELETE "$apiPath/athena-institute.net/account/cuid
-fc794872-7b9d-4ff2-a496-f6849c2939a0"

Sample Response

If the delete is successful, no JSON will be returned.

Errors

The API will return an error if the cuid is not found

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

© Copyright Cirrus Identity, Inc.

Blog comments