# Cirrus Identity Identities API ## Permissions Identities API credentials are [managed by organizational admins](https://docs.cirrusidentity.com/managed-identities/administration/api-access.html) in the Cirrus Console. ## Identities Identity objects are parent records that track information or assets associated with a user. ## Attribute Collections Attribute collections are bundles of attributes associated with a specific authority, such as a department or a credential. ### Remote Credentials Remote credentials are a special type of attribute collection, used to pre-link an identity record with a credential issued by an authentication provider *prior* to that credential being seen by a Cirrus Proxy. Remote credentials ensure that authentication at a Proxy with a particular authentication provider credential results in association with the correct pre-provisioned identity record. Because remote credential objects represent a remote (external) authentication provider, only the authority and UID (credential identifier) are permitted; no additional attributes may be provided. Remote credential attribute collections are included in the response of read operations that include `attributeCollections` in their output (i.e., `GET /list/byAttributeCollection/{environment}` and `GET /fetch/{cirrusId}`). The `attributes` member of any remote credential attribute collection will always be an empty object (i.e., `"attributes": {}`). ## OrgBrandedID OrgBrandedID is a hosted authentication provider option included with many Cirrus Identity subscriptions. Version: 1.1.0 Authentication: - HTTPBasic: http (basic) ## Fetch Permissions `GET /permissions` Return permissions for the current credential. Properties in the permissions object: - `username`: API credential username currently being used. - `orgDomain`: the organizational domain for which the credential was provisioned. - `environments`: either `test` or `prod`. - `environments..permissions`: an array of permissions in the specified identity environment. - `admin-all`: All available identity record permissions, including permissions introduced in the future. - `read`: Read access to identity records. - `write`: Write access to identity records. - `environments..customerUidKeys`: an array of customer-defined UID keys which the API credential may use when creating identities. Please contact Cirrus Identity Support for additional information. - `environments..attributeAuthorities`: an array of attribute authority identifiers which the API credential may use when creating identities or creating/modifying attribute collections. Please contact Cirrus Identity Support for additional information. - `obid`: an array of permissions for OBID accounts. These permissions apply in both the `test` and `prod` environments. - `read`: Read access to OBID account attribute collections. - `write`: May auto-create an OBID account at identity creation time, or create an OBID account for a pre-existing identity. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Responses: - 200: Success Content type: application/json Type: IdentitiesApiUserPermissionsModel model for user/permissions model (for identities API) Schema: [IdentitiesApiUserPermissionsModel](/identities-api/schemas/identitiesapiuserpermissionsmodel-294e34917d.md) - `username` (required) Type: string - `orgDomain` (required) Type: string - `environments` (optional) Type: object Map of linkgroup names to linkgroup permissions default: {} Additional properties: Reference: [LinkGroup](/identities-api/schemas/linkgroup-dbde2db3db.md); Type: LinkGroup linkgroup model - `obid` (optional) Type: Array List of OBID permissions default: [] Items: Type: string ```json { "username": "KQRAMJQXENIABXTZ", "orgDomain": "athena-institute.net", "environments": { "prod": { "permissions": [ "admin-all", "read", "write" ], "customerUidKeys": [ "athena:netId" ], "attributeAuthorities": [ "parking", "foundation" ] }, "test": { "permissions": [ "admin-all", "read", "write" ], "customerUidKeys": [ "athena:netId" ], "attributeAuthorities": [ "parking", "foundation" ] } }, "obid": [ "read", "write" ] } ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X GET "${BASE_URL}"'/identities/v1/permissions' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/permissions', { method: 'GET', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.get( base_url + '/identities/v1/permissions', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## List Identities `GET /list/{environment}` List all identity records for a specific environment (`test` or `prod`). Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `environment` (path, IdentityEnvironment, required) - identity environment Type: IdentityEnvironment identity environment Schema: [IdentityEnvironment](/identities-api/schemas/identityenvironment-345e0efae6.md) enum: ["test","prod"] - `page_idx` (query, integer, optional) - requested page index Type: integer requested page index default: 1 minimum: 1 - `page_size` (query, integer, optional) - requested number of items per page Type: integer requested number of items per page default: 10 minimum: 1 maximum: 50 - `sort_key` (query, IdentityListSortKey, optional) - sort key Type: IdentityListSortKey sort key Schema: [IdentityListSortKey](/identities-api/schemas/identitylistsortkey-48f2ced11c.md) default: "createTime" enum: ["cirrusUid","sn","givenName","mail","createTime","lastUpdateTime"] - `sort_order` (query, IdentityListSortOrder, optional) - sort order Type: IdentityListSortOrder sort order Schema: [IdentityListSortOrder](/identities-api/schemas/identitylistsortorder-0f73f3588b.md) default: "asc" enum: ["asc","desc"] - `search_term` (query, string | null, optional) - optional search term Type: string | null optional search term Examples: ```json [ "hugohail@example.edu" ] ``` anyOf: Type: string Type: null Responses: - 200: Successful Response Content type: application/json Type: Page_IdentityModelBase_ Schema: [Page_IdentityModelBase_](/identities-api/schemas/page-identitymodelbase-cf739db49c.md) - `items` (required) Type: Array list of items on this page Items: Reference: [IdentityModelBase](/identities-api/schemas/identitymodelbase-2589bb3c1a.md); Type: IdentityModelBase base identity model - `total_items` (required) Type: integer total number of items minimum: 0 - `page_cnt` (required) Type: integer total number of pages minimum: 0 - `page_size` (required) Type: integer number of items on this page minimum: 0 - `page_idx` (required) Type: integer current page index minimum: 1 - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X GET "${BASE_URL}"'/identities/v1/list/test?page_idx=1&page_size=10&sort_key=createTime&sort_order=asc' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/list/test?page_idx=1&page_size=10&sort_key=createTime&sort_order=asc', { method: 'GET', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.get( base_url + '/identities/v1/list/test?page_idx=1&page_size=10&sort_key=createTime&sort_order=asc', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## List Identities By Attr Collection `GET /list/byAttributeCollection/{environment}` List all identity records associated with a specific `attributeCollectionAuthority` (e.g., records containing an alumni attribute collection), or a combination of `attributeCollectionAuthority` and `uid` (e.g., find the alumni record with alumni uid of '1234567'). Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `environment` (path, IdentityEnvironment, required) - identity environment Type: IdentityEnvironment identity environment Schema: [IdentityEnvironment](/identities-api/schemas/identityenvironment-345e0efae6.md) enum: ["test","prod"] - `attributeAuthority` (query, string, required) - attribute authority identitifer Type: string attribute authority identitifer - `attributeAuthorityUid` (query, string, optional) - unique UID assigned by attribute authority Type: string unique UID assigned by attribute authority - `page_idx` (query, integer, optional) Type: integer default: 1 minimum: 1 - `page_size` (query, integer, optional) Type: integer default: 10 minimum: 1 maximum: 50 - `sort_key` (query, IdentityListSortKey, optional) Type: IdentityListSortKey enum for allowed fields to sort identity list by Schema: [IdentityListSortKey](/identities-api/schemas/identitylistsortkey-48f2ced11c.md) default: "createTime" enum: ["id","cirrusUid","sn","givenName","mail","createTime","lastUpdateTime"] - `sort_order` (query, IdentityListSortOrder, optional) Type: IdentityListSortOrder enum for allowed orders to sort identity list by Schema: [IdentityListSortOrder](/identities-api/schemas/identitylistsortorder-0f73f3588b.md) default: "asc" enum: ["asc","desc"] Responses: - 200: Successful Response Content type: application/json Type: Page_IdentityModel_ Schema: [Page_IdentityModel_](/identities-api/schemas/page-identitymodel-0245038f7a.md) - `items` (required) Type: Array list of items on this page Items: Reference: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md); Type: IdentityModel full identity model - `total_items` (required) Type: integer total number of items minimum: 0 - `page_cnt` (required) Type: integer total number of pages minimum: 0 - `page_size` (required) Type: integer number of items on this page minimum: 0 - `page_idx` (required) Type: integer current page index minimum: 1 - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X GET "${BASE_URL}"'/identities/v1/list/byAttributeCollection/test?attributeAuthority=string&page_idx=1&page_size=10&sort_key=createTime&sort_order=asc' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/list/byAttributeCollection/test?attributeAuthority=string&page_idx=1&page_size=10&sort_key=createTime&sort_order=asc', { method: 'GET', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.get( base_url + '/identities/v1/list/byAttributeCollection/test?attributeAuthority=string&page_idx=1&page_size=10&sort_key=createTime&sort_order=asc', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## Search Identities `GET /search/{environment}/{searchTerm}` List `cirrusUid` values for identity records matching search term. Search includes attribute collections. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `environment` (path, IdentityEnvironment, required) - identity environment Type: IdentityEnvironment identity environment Schema: [IdentityEnvironment](/identities-api/schemas/identityenvironment-345e0efae6.md) enum: ["test","prod"] - `searchTerm` (path, string, required) - term to use in search; will be sub-string matched against name and email fields in identity and linked attributeCollections Type: string term to use in search; will be sub-string matched against name and email fields in identity and linked attributeCollections Responses: - 200: Success Content type: application/json Type: Array Items: Type: string ```json [ "2ca73926-1c6a-44e9-8fc1-6c0c835d4a15", "2d615256-c822-4435-bf38-d36ba3c0f6c4", "9b8dadb8-62c1-4461-a4d7-2201a1cac407" ] ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X GET "${BASE_URL}"'/identities/v1/search/test/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/search/test/string', { method: 'GET', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.get( base_url + '/identities/v1/search/test/string', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## Fetch Identity `GET /fetch/{cirrusUid}` Retrieve a single identity record by `cirrusUid`. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record Responses: - 200: Successful Response Content type: application/json Type: IdentityModel full identity model Schema: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institite.net" ] ``` anyOf: Type: string Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string Type: null - `sn` (optional) Type: string | null Surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string Type: null - `createTime` (required) Type: string, date-time identity creation timestamp - `lastUpdateTime` (required) Type: string, date-time identity last update timestamp - `attributeCollections` (optional) Type: Array | null list of `AttributeCollectionOutput` anyOf: Type: Array Items: Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput output attribute collection model Type: null Examples: ```json [ { "attributeCollections": [ { "attributeCollectionAuthority": "https://athena-guest.idp.cirrusidentity.com/idp", "attributeCollectionAuthorityType": "obid", "attributes": { "scope": [ "athena-guest.idp.cirrusidentity.com" ], "urn:oid:0.9.2342.19200300.100.1.1": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" ], "urn:oid:0.9.2342.19200300.100.1.3": [ "aarcus@athena-institute.net" ], "urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c@athena-guest.idp.cirrusidentity.com" ], "urn:oid:2.16.840.1.113730.3.1.241": [ "Alice Arcus" ], "urn:oid:2.5.4.3": [ "Alice Arcus" ], "urn:oid:2.5.4.4": [ "Arcus" ], "urn:oid:2.5.4.42": [ "Alice" ] }, "createTime": "2025-10-31T19:12:08+00:00", "credentialLastUsed": "2026-06-04T17:16:35+00:00", "lastUpdateTime": "2025-10-31T19:12:08+00:00", "uid": "cuid-8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" }, { "attributeCollectionAuthority": "AthenaID", "attributeCollectionAuthorityType": "sor", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] }, "createTime": "2025-11-02T01:24:00+00:00", "lastUpdateTime": "2025-11-02T01:24:00+00:00", "uid": "ai-12345" } ], "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "createTime": "2025-10-31T19:12:07+00:00", "givenName": "Alice", "lastUpdateTime": "2025-10-31T19:12:07+00:00", "mail": "aarcus@athena-institute.net", "sn": "Arcus" } ] ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X GET "${BASE_URL}"'/identities/v1/fetch/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/fetch/string', { method: 'GET', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.get( base_url + '/identities/v1/fetch/string', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## Create Identity `POST /create/{environment}` Create an identity record, including optional additions as permitted for your credential: - `obid` - Create an OrgBrandedID sign-in credential for the identity, inviting the user to set a password for it, e.g.: ``` "obid": true ``` - `quiet` - Suppress any user-facing emails that might be triggered as a result of account creation - e.g., an OrgBrandedID account setup email ``` "quiet": true ``` - `attributeCollections` - Create one or more authorized types of attribute collections for the identity, e.g.: ``` "attributeCollections": [ { "attributeCollectionAuthority": "alumni", "uid": "al-12345", "attributes": { "alumniId": [ "al-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } } ] ``` - `remoteCredentials` - Create one or more remote credentials for the identity, e.g.: ``` "remoteCredentials": [ { "remoteCredentialAuthority": "https://shib.athena-institute.net/idp/shibboleth", "uid": "hugohail123" } ] ``` - `customerUidGen` - Auto-generate an identifier with a format customized to your organization, e.g.: ``` "customerUidGen": "athenaCustomId" ``` Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `environment` (path, IdentityEnvironment, required) - identity environment Type: IdentityEnvironment identity environment Schema: [IdentityEnvironment](/identities-api/schemas/identityenvironment-345e0efae6.md) enum: ["test","prod"] Request body: application/json (required) Type: IdentityCreateInput model for creating a new identity record Schema: [IdentityCreateInput](/identities-api/schemas/identitycreateinput-b5a7def79f.md) - `mail` (required) Type: string, email email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` - `givenName` (required) Type: string given name maxLength: 255 Examples: ```json [ "Alice" ] ``` - `sn` (required) Type: string surname maxLength: 255 Examples: ```json [ "Arcus" ] ``` - `customerUidGen` (optional) Type: string | null optional Cirrus-provided key for generating customer-defined UIDs anyOf: Type: string Type: null - `obid` (optional) Type: boolean whether to create/link an OrgBrandedID account for `mail` value default: false - `quiet` (optional) Type: boolean suppress any user-facing emails that might be triggered as a result of account creation - e.g., an OrgBrandedID account setup email default: false - `allowDuplicateEmail` (optional) Type: boolean whether to allow creation of an identity record with an email address already associated with another identity default: false - `attributeCollections` (optional) Type: Array | null optional list of attribute collections to create and link to identity record anyOf: Type: Array Items: Reference: [AttributeCollectionInput](/identities-api/schemas/attributecollectioninput-8b18f20195.md); Type: AttributeCollectionInput attribute collection model Type: null - `remoteCredentials` (optional) Type: Array | null optional list of remote credential (authority, uid) pairs to create and link to identity record anyOf: Type: Array Items: Reference: [RemoteCredentialInput](/identities-api/schemas/remotecredentialinput-78aa5053c9.md); Type: RemoteCredentialInput remote credential model Type: null Examples: ```json [ { "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "obid": false, "quiet": false, "allowDuplicateEmail": false } ] ``` Responses: - 201: Successful Response Content type: application/json Type: IdentityModel full identity model Schema: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institite.net" ] ``` anyOf: Type: string Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string Type: null - `sn` (optional) Type: string | null Surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string Type: null - `createTime` (required) Type: string, date-time identity creation timestamp - `lastUpdateTime` (required) Type: string, date-time identity last update timestamp - `attributeCollections` (optional) Type: Array | null list of `AttributeCollectionOutput` anyOf: Type: Array Items: Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput output attribute collection model Type: null Examples: ```json [ { "attributeCollections": [ { "attributeCollectionAuthority": "https://athena-guest.idp.cirrusidentity.com/idp", "attributeCollectionAuthorityType": "obid", "attributes": { "scope": [ "athena-guest.idp.cirrusidentity.com" ], "urn:oid:0.9.2342.19200300.100.1.1": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" ], "urn:oid:0.9.2342.19200300.100.1.3": [ "aarcus@athena-institute.net" ], "urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c@athena-guest.idp.cirrusidentity.com" ], "urn:oid:2.16.840.1.113730.3.1.241": [ "Alice Arcus" ], "urn:oid:2.5.4.3": [ "Alice Arcus" ], "urn:oid:2.5.4.4": [ "Arcus" ], "urn:oid:2.5.4.42": [ "Alice" ] }, "createTime": "2025-10-31T19:12:08+00:00", "credentialLastUsed": "2026-06-04T17:16:35+00:00", "lastUpdateTime": "2025-10-31T19:12:08+00:00", "uid": "cuid-8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" }, { "attributeCollectionAuthority": "AthenaID", "attributeCollectionAuthorityType": "sor", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] }, "createTime": "2025-11-02T01:24:00+00:00", "lastUpdateTime": "2025-11-02T01:24:00+00:00", "uid": "ai-12345" } ], "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "createTime": "2025-10-31T19:12:07+00:00", "givenName": "Alice", "lastUpdateTime": "2025-10-31T19:12:07+00:00", "mail": "aarcus@athena-institute.net", "sn": "Arcus" } ] ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 409: Conflict Content type: application/json - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X POST "${BASE_URL}"'/identities/v1/create/test' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "obid": false, "quiet": false, "allowDuplicateEmail": false }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "obid": false, "quiet": false, "allowDuplicateEmail": false }`; const response = await fetch(baseUrl + '/identities/v1/create/test', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "obid": false, "quiet": false, "allowDuplicateEmail": false }''' response = requests.post( base_url + '/identities/v1/create/test', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Modify Identity `PATCH /modify/{cirrusUid}` Modify core attributes of identity record. The attributes that may be modified are: - `givenName` - `sn` - `mail` Any combination of these attributes may be provided; only provided attribute values will be updated. Attributes with a value of `null` will be ignored (treated the same as omitting them). If the `mail` attribute value is present on another identity in the same environment, a `409 Conflict` error will be returned. If you wish to override this behavior, and allow duplicate email values, pass `true` for the boolean parameter, `allowDuplicateEmail`. The updated identity record is returned upon success. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record Request body: application/json (required) Type: IdentityModifyInput model for modifying base properties on existing identity record Schema: [IdentityModifyInput](/identities-api/schemas/identitymodifyinput-71949ff41d.md) - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` anyOf: Type: string, email Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string maxLength: 255 Type: null - `sn` (optional) Type: string | null surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string maxLength: 255 Type: null - `allowDuplicateEmail` (optional) Type: boolean whether to allow creation of an identity record with an email address already associated with another identity default: false Responses: - 200: Successful Response Content type: application/json Type: IdentityModel full identity model Schema: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institite.net" ] ``` anyOf: Type: string Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string Type: null - `sn` (optional) Type: string | null Surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string Type: null - `createTime` (required) Type: string, date-time identity creation timestamp - `lastUpdateTime` (required) Type: string, date-time identity last update timestamp - `attributeCollections` (optional) Type: Array | null list of `AttributeCollectionOutput` anyOf: Type: Array Items: Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput output attribute collection model Type: null Examples: ```json [ { "attributeCollections": [ { "attributeCollectionAuthority": "https://athena-guest.idp.cirrusidentity.com/idp", "attributeCollectionAuthorityType": "obid", "attributes": { "scope": [ "athena-guest.idp.cirrusidentity.com" ], "urn:oid:0.9.2342.19200300.100.1.1": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" ], "urn:oid:0.9.2342.19200300.100.1.3": [ "aarcus@athena-institute.net" ], "urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c@athena-guest.idp.cirrusidentity.com" ], "urn:oid:2.16.840.1.113730.3.1.241": [ "Alice Arcus" ], "urn:oid:2.5.4.3": [ "Alice Arcus" ], "urn:oid:2.5.4.4": [ "Arcus" ], "urn:oid:2.5.4.42": [ "Alice" ] }, "createTime": "2025-10-31T19:12:08+00:00", "credentialLastUsed": "2026-06-04T17:16:35+00:00", "lastUpdateTime": "2025-10-31T19:12:08+00:00", "uid": "cuid-8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" }, { "attributeCollectionAuthority": "AthenaID", "attributeCollectionAuthorityType": "sor", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] }, "createTime": "2025-11-02T01:24:00+00:00", "lastUpdateTime": "2025-11-02T01:24:00+00:00", "uid": "ai-12345" } ], "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "createTime": "2025-10-31T19:12:07+00:00", "givenName": "Alice", "lastUpdateTime": "2025-10-31T19:12:07+00:00", "mail": "aarcus@athena-institute.net", "sn": "Arcus" } ] ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 409: Conflict Content type: application/json - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X PATCH "${BASE_URL}"'/identities/v1/modify/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "allowDuplicateEmail": false }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "allowDuplicateEmail": false }`; const response = await fetch(baseUrl + '/identities/v1/modify/string', { method: 'PATCH', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "mail": "aarcus@athena-institute.net", "givenName": "Alice", "sn": "Arcus", "allowDuplicateEmail": false }''' response = requests.patch( base_url + '/identities/v1/modify/string', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Create Attribute Collection `POST /attributeCollections/create/{cirrusUid}` Create a new attribute collection under an authorized authority for an existing identity record. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record Request body: application/json (required) Type: AttributeCollectionInput attribute collection model Schema: [AttributeCollectionInput](/identities-api/schemas/attributecollectioninput-8b18f20195.md) - `attributeCollectionAuthority` (required) Type: string identifier of attribute collection authority Examples: ```json [ "AthenaID" ] ``` - `uid` (required) Type: string unique identifier for attribute authority collection instance Examples: ```json [ "ai-12345" ] ``` - `attributes` (optional) Type: object object of attribute keys and list of values default: {} Examples: ```json [ { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } ] ``` Additional properties: true Responses: - 201: Successful Response Content type: application/json Type: AttributeCollectionCreateOrModifyOutput wrapper for returning attribute collections along with cirrusUid Schema: [AttributeCollectionCreateOrModifyOutput](/identities-api/schemas/attributecollectioncreateormodifyoutput-fac9e6d321.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `attributeCollection` (required) Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput created/modified attributeCollection - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 409: Conflict Content type: application/json ```json { "detail": "record already exists" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X POST "${BASE_URL}"'/identities/v1/attributeCollections/create/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }`; const response = await fetch(baseUrl + '/identities/v1/attributeCollections/create/string', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }''' response = requests.post( base_url + '/identities/v1/attributeCollections/create/string', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Modify Attribute Collection `PUT /attributeCollections/modify/{cirrusUid}` Modify a specific attribute collection under an authorized authority for an identity record. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record - `overwrite` (query, boolean, optional) - completely overwrite attributes (`true`) or merge (default, `false`) Type: boolean completely overwrite attributes (`true`) or merge (default, `false`) default: false Request body: application/json (required) Type: AttributeCollectionInput attribute collection model Schema: [AttributeCollectionInput](/identities-api/schemas/attributecollectioninput-8b18f20195.md) - `attributeCollectionAuthority` (required) Type: string identifier of attribute collection authority Examples: ```json [ "AthenaID" ] ``` - `uid` (required) Type: string unique identifier for attribute authority collection instance Examples: ```json [ "ai-12345" ] ``` - `attributes` (optional) Type: object object of attribute keys and list of values default: {} Examples: ```json [ { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } ] ``` Additional properties: true Responses: - 200: Successful Response Content type: application/json Type: AttributeCollectionCreateOrModifyOutput wrapper for returning attribute collections along with cirrusUid Schema: [AttributeCollectionCreateOrModifyOutput](/identities-api/schemas/attributecollectioncreateormodifyoutput-fac9e6d321.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `attributeCollection` (required) Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput created/modified attributeCollection - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X PUT "${BASE_URL}"'/identities/v1/attributeCollections/modify/string?overwrite=false' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }`; const response = await fetch(baseUrl + '/identities/v1/attributeCollections/modify/string?overwrite=false', { method: 'PUT', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "attributeCollectionAuthority": "AthenaID", "uid": "ai-12345", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } }''' response = requests.put( base_url + '/identities/v1/attributeCollections/modify/string?overwrite=false', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete Attribute Collection `DELETE /attributeCollections/delete/{cirrusUid}` Delete a specific attribute collection under an authorized authority from an identity record. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record - `attributeAuthority` (query, string, required) - identifier of attribute collection authority Type: string identifier of attribute collection authority - `attributeAuthorityUid` (query, string, required) - unique identifier for attribute collection Type: string unique identifier for attribute collection Responses: - 204: Successful Response - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X DELETE "${BASE_URL}"'/identities/v1/attributeCollections/delete/string?attributeAuthority=string&attributeAuthorityUid=string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/attributeCollections/delete/string?attributeAuthority=string&attributeAuthorityUid=string', { method: 'DELETE', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.delete( base_url + '/identities/v1/attributeCollections/delete/string?attributeAuthority=string&attributeAuthorityUid=string', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## Create Remote Credential `POST /remoteCredentials/create/{cirrusUid}` Create a new remote credential under an existing identity record. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record Request body: application/json (required) Type: RemoteCredentialInput remote credential model Schema: [RemoteCredentialInput](/identities-api/schemas/remotecredentialinput-78aa5053c9.md) - `remoteCredentialAuthority` (required) Type: string identifier of remote credential authority Examples: ```json [ "https://athena-institute.net/idp", "urn:mace:incommon:athena-institute.net" ] ``` - `uid` (required) Type: string unique identifier at remote credential authority Examples: ```json [ "ai-12345" ] ``` Responses: - 201: Successful Response Content type: application/json Type: AttributeCollectionCreateOrModifyOutput wrapper for returning attribute collections along with cirrusUid Schema: [AttributeCollectionCreateOrModifyOutput](/identities-api/schemas/attributecollectioncreateormodifyoutput-fac9e6d321.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `attributeCollection` (required) Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput created/modified attributeCollection - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 409: Conflict Content type: application/json ```json { "detail": "record already exists" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X POST "${BASE_URL}"'/identities/v1/remoteCredentials/create/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "remoteCredentialAuthority": "https://athena-institute.net/idp", "uid": "ai-12345" }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "remoteCredentialAuthority": "https://athena-institute.net/idp", "uid": "ai-12345" }`; const response = await fetch(baseUrl + '/identities/v1/remoteCredentials/create/string', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "remoteCredentialAuthority": "https://athena-institute.net/idp", "uid": "ai-12345" }''' response = requests.post( base_url + '/identities/v1/remoteCredentials/create/string', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete Remote Credential `DELETE /remoteCredentials/delete/{cirrusUid}` Delete a specific remote credential under an identity record. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record - `remoteCredentialAuthority` (query, string, required) - identifier of remote credential authority Type: string identifier of remote credential authority - `remoteCredentialUid` (query, string, required) - unique identifier at remote credential authority Type: string unique identifier at remote credential authority Responses: - 204: Successful Response - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X DELETE "${BASE_URL}"'/identities/v1/remoteCredentials/delete/string?remoteCredentialAuthority=string&remoteCredentialUid=string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/remoteCredentials/delete/string?remoteCredentialAuthority=string&remoteCredentialUid=string', { method: 'DELETE', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.delete( base_url + '/identities/v1/remoteCredentials/delete/string?remoteCredentialAuthority=string&remoteCredentialUid=string', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## Create Obid `POST /obids/create/{cirrusUid}` Create a new OrgBrandedID sign-in credential for an existing identity record, sending an onboarding email to the designated email address. The `quiet` flag can be used to suppress the OrgBrandedID account setup email. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record Request body: application/json (required) Type: OrgBrandedIdAccountCreateInput model for creating a new OBID account Schema: [OrgBrandedIdAccountCreateInput](/identities-api/schemas/orgbrandedidaccountcreateinput-68329e5382.md) - `givenName` (optional) Type: string | null first name Examples: ```json [ "Alice" ] ``` anyOf: Type: string maxLength: 255 Type: null - `surname` (optional) Type: string | null last name Examples: ```json [ "Arcus" ] ``` anyOf: Type: string maxLength: 255 Type: null - `email` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` anyOf: Type: string, email Type: null - `quiet` (optional) Type: boolean suppress OrgBrandedID account setup email default: false Responses: - 201: Success Content type: application/json Type: AttributeCollectionCreateOrModifyOutput wrapper for returning attribute collections along with cirrusUid Schema: [AttributeCollectionCreateOrModifyOutput](/identities-api/schemas/attributecollectioncreateormodifyoutput-fac9e6d321.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `attributeCollection` (required) Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput created/modified attributeCollection ```json { "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "attributeCollection": { "attributeCollectionAuthority": "https://athena-guest.idp.cirrusidentity.com/idp", "uid": "cuid-8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c", "attributes": { "urn:oid:2.5.4.4": [ "Arcus" ], "urn:oid:0.9.2342.19200300.100.1.3": [ "aarcus@athena-institute.net" ], "urn:oid:2.16.840.1.113730.3.1.241": [ "Alice Arcus" ], "urn:oid:2.5.4.3": [ "Alice Arcus" ], "urn:oid:0.9.2342.19200300.100.1.1": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" ], "urn:oid:2.5.4.42": [ "Alice" ], "scope": [ "athena-guest.idp.cirrusidentity.com" ], "urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c@athena-guest.idp.cirrusidentity.com" ] }, "createTime": "2025-10-31T19:12:08+00:00", "lastUpdateTime": "2025-10-31T19:12:08+00:00", "attributeCollectionAuthorityType": "obid" } } ``` - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 409: Conflict Content type: application/json ```json { "detail": "OBID Error: Account for [user@domain.edu] exists and cannot be created again." } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X POST "${BASE_URL}"'/identities/v1/obids/create/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \ -H 'Content-Type: application/json' \ --data-raw '{ "givenName": "Alice", "surname": "Arcus", "email": "aarcus@athena-institute.net", "quiet": false }' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const body = `{ "givenName": "Alice", "surname": "Arcus", "email": "aarcus@athena-institute.net", "quiet": false }`; const response = await fetch(baseUrl + '/identities/v1/obids/create/string', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' body = '''{ "givenName": "Alice", "surname": "Arcus", "email": "aarcus@athena-institute.net", "quiet": false }''' response = requests.post( base_url + '/identities/v1/obids/create/string', data=body.encode('utf-8'), headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Send Obid Credential Email `POST /obids/{cirrusUid}/sendCredentialEmail/{cuid}` Send a credential email for the OBID account `cuid` associated with identity `cirrusUid`. If the OBID account is in either the `BOOTSTRAP` or `INACTIVE` state, the "account activation" email will be sent. Otherwise, the "password reset" email will be sent. Authentication (security requirement alternatives): ```json [ { "HTTPBasic": [] } ] ``` - HTTPBasic: http (basic) Parameters: - `cirrusUid` (path, string, required) - `cirrusUid` of identity record Type: string `cirrusUid` of identity record - `cuid` (path, string, required) - identifier of OBID account (begins with `cuid-`) Type: string identifier of OBID account (begins with `cuid-`) Responses: - 204: Successful Response - 401: Unauthorized Content type: application/json ```json { "detail": "not authorized" } ``` - 404: Not Found Content type: application/json ```json { "detail": "record not found" } ``` - 409: Not Found Content type: application/json ```json { "detail": "OBID account 645aab71-bdfd-4b36-98c0-e9d531731f1c is in SUSPENDED status and can't be reset" } ``` - 422: Validation Error Content type: application/json Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError - 500: Internal Server Error Content type: application/json ```json { "detail": "database error: ..." } ``` ## Examples ### cURL ```bash BASE_URL='YOUR_API_ORIGIN' curl -X POST "${BASE_URL}"'/identities/v1/obids/string/sendCredentialEmail/string' \ -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' ``` ### JavaScript ```javascript const baseUrl = 'YOUR_API_ORIGIN'; const response = await fetch(baseUrl + '/identities/v1/obids/string/sendCredentialEmail/string', { method: 'POST', headers: { 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, }); const data = await response.text(); ``` ### Python ```python import requests base_url='YOUR_API_ORIGIN' response = requests.post( base_url + '/identities/v1/obids/string/sendCredentialEmail/string', headers={ 'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE', }, ) print(response.text) ``` ## AttributeCollectionAuthorityType Type: AttributeCollectionAuthorityType enum for deployment patterns Schema: [AttributeCollectionAuthorityType](/identities-api/schemas/attributecollectionauthoritytype-eac0393eb0.md) enum: ["sor","obid","gateway"] ## AttributeCollectionCreateOrModifyOutput Type: AttributeCollectionCreateOrModifyOutput wrapper for returning attribute collections along with cirrusUid Schema: [AttributeCollectionCreateOrModifyOutput](/identities-api/schemas/attributecollectioncreateormodifyoutput-fac9e6d321.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `attributeCollection` (required) Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput created/modified attributeCollection ## AttributeCollectionInput Type: AttributeCollectionInput attribute collection model Schema: [AttributeCollectionInput](/identities-api/schemas/attributecollectioninput-8b18f20195.md) - `attributeCollectionAuthority` (required) Type: string identifier of attribute collection authority Examples: ```json [ "AthenaID" ] ``` - `uid` (required) Type: string unique identifier for attribute authority collection instance Examples: ```json [ "ai-12345" ] ``` - `attributes` (optional) Type: object object of attribute keys and list of values default: {} Examples: ```json [ { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } ] ``` Additional properties: true ## AttributeCollectionOutput Type: AttributeCollectionOutput output attribute collection model Schema: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md) - `attributeCollectionAuthority` (required) Type: string identifier of attribute collection authority Examples: ```json [ "AthenaID" ] ``` - `uid` (required) Type: string unique identifier for attribute authority collection instance Examples: ```json [ "ai-12345" ] ``` - `attributes` (optional) Type: object object of attribute keys and list of values default: {} Examples: ```json [ { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] } ] ``` Additional properties: true - `createTime` (required) Type: string, date-time attribute collection creation timestamp - `lastUpdateTime` (required) Type: string, date-time attribute collection last update timestamp - `credentialLastUsed` (optional) Type: string | null last time used, if attribute collection represents a credential anyOf: Type: string, date-time Type: null - `attributeCollectionAuthorityType` (required) Reference: [AttributeCollectionAuthorityType](/identities-api/schemas/attributecollectionauthoritytype-eac0393eb0.md); Type: AttributeCollectionAuthorityType type of attribute collection authority enum: ["sor","obid","gateway"] readOnly: true ## HTTPValidationError Type: HTTPValidationError Schema: [HTTPValidationError](/identities-api/schemas/httpvalidationerror-231eeffce0.md) - `detail` (optional) Type: Array Items: Reference: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError ## IdentitiesApiUserPermissionsModel Type: IdentitiesApiUserPermissionsModel model for user/permissions model (for identities API) Schema: [IdentitiesApiUserPermissionsModel](/identities-api/schemas/identitiesapiuserpermissionsmodel-294e34917d.md) - `username` (required) Type: string - `orgDomain` (required) Type: string - `environments` (optional) Type: object Map of linkgroup names to linkgroup permissions default: {} Additional properties: Reference: [LinkGroup](/identities-api/schemas/linkgroup-dbde2db3db.md); Type: LinkGroup linkgroup model - `obid` (optional) Type: Array List of OBID permissions default: [] Items: Type: string ## IdentityCreateInput Type: IdentityCreateInput model for creating a new identity record Schema: [IdentityCreateInput](/identities-api/schemas/identitycreateinput-b5a7def79f.md) - `mail` (required) Type: string, email email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` - `givenName` (required) Type: string given name maxLength: 255 Examples: ```json [ "Alice" ] ``` - `sn` (required) Type: string surname maxLength: 255 Examples: ```json [ "Arcus" ] ``` - `customerUidGen` (optional) Type: string | null optional Cirrus-provided key for generating customer-defined UIDs anyOf: Type: string Type: null - `obid` (optional) Type: boolean whether to create/link an OrgBrandedID account for `mail` value default: false - `quiet` (optional) Type: boolean suppress any user-facing emails that might be triggered as a result of account creation - e.g., an OrgBrandedID account setup email default: false - `allowDuplicateEmail` (optional) Type: boolean whether to allow creation of an identity record with an email address already associated with another identity default: false - `attributeCollections` (optional) Type: Array | null optional list of attribute collections to create and link to identity record anyOf: Type: Array Items: Reference: [AttributeCollectionInput](/identities-api/schemas/attributecollectioninput-8b18f20195.md); Type: AttributeCollectionInput attribute collection model Type: null - `remoteCredentials` (optional) Type: Array | null optional list of remote credential (authority, uid) pairs to create and link to identity record anyOf: Type: Array Items: Reference: [RemoteCredentialInput](/identities-api/schemas/remotecredentialinput-78aa5053c9.md); Type: RemoteCredentialInput remote credential model Type: null ## IdentityEnvironment Type: IdentityEnvironment enum for allowed linking environments Schema: [IdentityEnvironment](/identities-api/schemas/identityenvironment-345e0efae6.md) enum: ["test","prod"] ## IdentityListSortKey Type: IdentityListSortKey enum for allowed fields to sort identity list by Schema: [IdentityListSortKey](/identities-api/schemas/identitylistsortkey-48f2ced11c.md) enum: ["id","cirrusUid","sn","givenName","mail","createTime","lastUpdateTime"] ## IdentityListSortOrder Type: IdentityListSortOrder enum for allowed orders to sort identity list by Schema: [IdentityListSortOrder](/identities-api/schemas/identitylistsortorder-0f73f3588b.md) enum: ["asc","desc"] ## IdentityModel Type: IdentityModel full identity model Schema: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institite.net" ] ``` anyOf: Type: string Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string Type: null - `sn` (optional) Type: string | null Surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string Type: null - `createTime` (required) Type: string, date-time identity creation timestamp - `lastUpdateTime` (required) Type: string, date-time identity last update timestamp - `attributeCollections` (optional) Type: Array | null list of `AttributeCollectionOutput` anyOf: Type: Array Items: Reference: [AttributeCollectionOutput](/identities-api/schemas/attributecollectionoutput-b54f0f0eb9.md); Type: AttributeCollectionOutput output attribute collection model Type: null Examples: ```json [ { "attributeCollections": [ { "attributeCollectionAuthority": "https://athena-guest.idp.cirrusidentity.com/idp", "attributeCollectionAuthorityType": "obid", "attributes": { "scope": [ "athena-guest.idp.cirrusidentity.com" ], "urn:oid:0.9.2342.19200300.100.1.1": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" ], "urn:oid:0.9.2342.19200300.100.1.3": [ "aarcus@athena-institute.net" ], "urn:oid:1.3.6.1.4.1.5923.1.1.1.6": [ "8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c@athena-guest.idp.cirrusidentity.com" ], "urn:oid:2.16.840.1.113730.3.1.241": [ "Alice Arcus" ], "urn:oid:2.5.4.3": [ "Alice Arcus" ], "urn:oid:2.5.4.4": [ "Arcus" ], "urn:oid:2.5.4.42": [ "Alice" ] }, "createTime": "2025-10-31T19:12:08+00:00", "credentialLastUsed": "2026-06-04T17:16:35+00:00", "lastUpdateTime": "2025-10-31T19:12:08+00:00", "uid": "cuid-8a37d4f4-d09f-4ac5-bf67-9e38f987bf1c" }, { "attributeCollectionAuthority": "AthenaID", "attributeCollectionAuthorityType": "sor", "attributes": { "athenaId": [ "ai-12345" ], "givenName": [ "Alice" ], "sn": [ "Arcus" ] }, "createTime": "2025-11-02T01:24:00+00:00", "lastUpdateTime": "2025-11-02T01:24:00+00:00", "uid": "ai-12345" } ], "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "createTime": "2025-10-31T19:12:07+00:00", "givenName": "Alice", "lastUpdateTime": "2025-10-31T19:12:07+00:00", "mail": "aarcus@athena-institute.net", "sn": "Arcus" } ] ``` ## IdentityModelBase Type: IdentityModelBase base identity model Schema: [IdentityModelBase](/identities-api/schemas/identitymodelbase-2589bb3c1a.md) - `cirrusUid` (required) Type: string `cirrusUid` of identity record Examples: ```json [ "a82113d1-7072-494f-91c5-be3dbe2db08d" ] ``` - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institite.net" ] ``` anyOf: Type: string Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string Type: null - `sn` (optional) Type: string | null Surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string Type: null - `createTime` (required) Type: string, date-time identity creation timestamp - `lastUpdateTime` (required) Type: string, date-time identity last update timestamp Examples: ```json [ { "cirrusUid": "a82113d1-7072-494f-91c5-be3dbe2db08d", "createTime": "2025-10-31T19:12:07+00:00", "givenName": "Alice", "lastUpdateTime": "2025-10-31T19:12:07+00:00", "mail": "aarcus@athena-institute.net", "sn": "Arcus" } ] ``` ## IdentityModifyInput Type: IdentityModifyInput model for modifying base properties on existing identity record Schema: [IdentityModifyInput](/identities-api/schemas/identitymodifyinput-71949ff41d.md) - `mail` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` anyOf: Type: string, email Type: null - `givenName` (optional) Type: string | null given name Examples: ```json [ "Alice" ] ``` anyOf: Type: string maxLength: 255 Type: null - `sn` (optional) Type: string | null surname Examples: ```json [ "Arcus" ] ``` anyOf: Type: string maxLength: 255 Type: null - `allowDuplicateEmail` (optional) Type: boolean whether to allow creation of an identity record with an email address already associated with another identity default: false ## LinkGroup Type: LinkGroup linkgroup model Schema: [LinkGroup](/identities-api/schemas/linkgroup-dbde2db3db.md) - `permissions` (optional) Type: Array List of permissions for org + link group default: [] Items: Type: string - `customerUidKeys` (optional) Type: Array List of Customer UID `tenantShortName:attributeCollectionAuthority` pairs default: [] Items: Type: string - `attributeAuthorities` (optional) Type: Array List of Customer attribute authorities default: [] Items: Type: string ## OrgBrandedIdAccountCreateInput Type: OrgBrandedIdAccountCreateInput model for creating a new OBID account Schema: [OrgBrandedIdAccountCreateInput](/identities-api/schemas/orgbrandedidaccountcreateinput-68329e5382.md) - `givenName` (optional) Type: string | null first name Examples: ```json [ "Alice" ] ``` anyOf: Type: string maxLength: 255 Type: null - `surname` (optional) Type: string | null last name Examples: ```json [ "Arcus" ] ``` anyOf: Type: string maxLength: 255 Type: null - `email` (optional) Type: string | null email address Examples: ```json [ "aarcus@athena-institute.net" ] ``` anyOf: Type: string, email Type: null - `quiet` (optional) Type: boolean suppress OrgBrandedID account setup email default: false ## Page_IdentityModelBase_ Type: Page_IdentityModelBase_ Schema: [Page_IdentityModelBase_](/identities-api/schemas/page-identitymodelbase-cf739db49c.md) - `items` (required) Type: Array list of items on this page Items: Reference: [IdentityModelBase](/identities-api/schemas/identitymodelbase-2589bb3c1a.md); Type: IdentityModelBase base identity model - `total_items` (required) Type: integer total number of items minimum: 0 - `page_cnt` (required) Type: integer total number of pages minimum: 0 - `page_size` (required) Type: integer number of items on this page minimum: 0 - `page_idx` (required) Type: integer current page index minimum: 1 ## Page_IdentityModel_ Type: Page_IdentityModel_ Schema: [Page_IdentityModel_](/identities-api/schemas/page-identitymodel-0245038f7a.md) - `items` (required) Type: Array list of items on this page Items: Reference: [IdentityModel](/identities-api/schemas/identitymodel-4d7b1c2967.md); Type: IdentityModel full identity model - `total_items` (required) Type: integer total number of items minimum: 0 - `page_cnt` (required) Type: integer total number of pages minimum: 0 - `page_size` (required) Type: integer number of items on this page minimum: 0 - `page_idx` (required) Type: integer current page index minimum: 1 ## RemoteCredentialInput Type: RemoteCredentialInput remote credential model Schema: [RemoteCredentialInput](/identities-api/schemas/remotecredentialinput-78aa5053c9.md) - `remoteCredentialAuthority` (required) Type: string identifier of remote credential authority Examples: ```json [ "https://athena-institute.net/idp", "urn:mace:incommon:athena-institute.net" ] ``` - `uid` (required) Type: string unique identifier at remote credential authority Examples: ```json [ "ai-12345" ] ``` ## ValidationError Type: ValidationError Schema: [ValidationError](/identities-api/schemas/validationerror-bdfaef14be.md) - `loc` (required) Type: Array Items: Type: string | integer anyOf: Type: string Type: integer - `msg` (required) Type: string - `type` (required) Type: string - `input` (optional) Type: any - `ctx` (optional) Type: object