List Invitations for a Domain uri /invitations/{domain} description Paginated listing of all the...
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