Data Model

To work with Cisco XDR APIs, you need to understand some concepts behind the users. The user data model follow this hierarchy:

  1. At the top level, there are Organizations.
  2. Each Organization can have many Users.
  3. Each User can have many Clients.

When you use the API or JWT, you will be faced with the same set of fields.

Retrieve user & org Data

If you log in and make an HTTP GET request to https://visibility.amp.cisco.com/iroh/profile/whoami, you will get a response with the following format:

{
    "user": ...,
    "org": ...
}

The user field points to a User object, and the org field points to an Org object.

Each entity is identified with a unique ID. All entities have other field(s) that should be displayed to the end user.

Org Model

Here is a JSON example of an Org model:

{
    "id":"some-unique-org-id",
    "name":"Cisco",
    "additional-scopes":["super" "sse"],
    "allow-all-role-to-login":true,
    "scim-status":"activated",
    "enabled?":true,
    "settings":{
        "allow-all-roles-to-login":false
    }
}

The Org model has the following fields:

Field Type Description
id String (Mandatory) A unique identifier for Cisco XDR Platform API.
name String Organization name. If provided, it should be user friendly.
additional-scopes [String] A list of additional scope(s) provided by users with a master role. For more information about scopes, see Authorization Access / Scopes.
scim-status String Can be either "activated" or "waiting-activation" for organizations that are not yet activated. An organization that is not activated can only configure modules and see its own profile.
allow-all-role-to-login Boolean If true, non-admins can login to IROH. Only user with a master role can edit this value at the top level of the object. If this value is not present, the value in the settings block is used. If none is set, the decision to allow a non-admin of an organization to log in is the default of the Identity Provider (IdP) of the user. The IdP can either be Secure Endpoint or Secure Malware Analytics. By default, Secure Endpoint non-admins are not allowed to log in. By default, Secure Malware Analytics allows non-admins to log in.
enabled? Boolean Only users with a master role can change this value. When disabled, no users of this organization can log in.
settings OrgSettings A user editable settings object. Only organization administrators can edit these settings.

The settings field contains an OrgSettings object whose only potential field is:
FieldTypeDescription
allow-all-role-to-loginBooleanIf the top-level similar flag is not set then:
  • If true, non-admin can log in to IROH.
  • If false only admin can log in.
  • If not set use the default value of the Identity Provider (false for Secure Endpoint, true for Secure Malware Analytics).

User Model

Here is a JSON example of an Org model:

{
    "user-id":"idb-amp:some-user-identifier",
    "org-id":"some-unique-org-id",
    "scopes":["enrich" "private-intel" "public-intel"],
    "additional-scopes":["super" "sse"],
    "idp-mappings": [{
        "idp":"idb-amp",
        "user-identity-id":"some-user-identifier",
        "organization-id":"some-org-id"}],
    "user-name":"Jane Doe",
    "user-email":"dev.null@cisco.com",
    "user-nick":"Jannie"
}

The Org model has the following fields:

Field Type Description
user-id String (Mandatory) A unique identifier for the user across all IROH.
org-id String (Mandatory) A unique identifier for the organization of the user across all IROH.
scopes [String] (Mandatory) A list of scopes.
additional-scopes [String] A list of additional scopes that can be set by users with a master role.
idp-mappings [IdPMapping] object Contains technical information about the mapping between the identifiers in IROH and from the Identity Providers. This mapping is useful for debugging purposes. It might be removed in the future and should not be used directly.
user-name String If provided, it displays the full user name.
user-nick String If provided, it displays the user nickname. This should be the preferred field to display the user identity to the user. The user-id is not user friendly.
user-email String If provided, the user email is displayed.